Skip to content

CLI reference

Reference

The agent3md CLI

agent3md is a small command-line tool over any agent.3md file. It exists in two forms with the same commands:

  • TypeScript (the reference): bun run cli <command> [file] [args] from a clone of the repo (or bun run src/cli.ts ...).
  • Rust (the native binary): agent3md <command> <file> [args] after cargo install agent3md.

In the TypeScript CLI the [file] is optional and defaults to the project's agent.3md; an argument is treated as the file when it exists on disk or ends in .3md. The examples below use agent.3md explicitly for clarity. The commands are new, manifest, skills, route, get, resolve, run, and (via the validator) validate.

new

Scaffold a fresh, valid agent. Writes <name>.3md by default (or a second argument as the output path) and refuses to overwrite an existing file.

bun run cli new my-agent
wrote my-agent.3md
next:
  bun run src/validate.ts my-agent.3md                 # check it conforms
  bun run src/cli.ts run my-agent.3md "find every TODO" pattern=TODO path=src
  bun run src/mcp.ts my-agent.3md                      # serve its skills over MCP

The scaffold has an identity plane plus two real command-backed skills (search via rg, json via jq).

manifest

Print the agent's name, persona, declared tools, and a body-less skill catalog (names, cost tags, bound commands, triggers). This is the cheap-to-keep-resident view.

bun run cli manifest agent.3md
dev
  persona: terminal-first; reaches for one precise command instead of reading files, and confirms before anything destructive
  tools:   rg, fd, jq, git, gh, curl
  skills:  7
    - search  ->  rg --line-number {pattern} {path}
        triggers: search, find, grep, code, pattern
    - files  ->  fd {glob} {dir}
        triggers: files, list, locate, glob, filenames
    ...
    - research
        triggers: research, web, online, docs, documentation, look up

Note that research has no -> command: it is a guidance-only skill.

skills

Just the skill names, one per line. Handy for scripting.

bun run cli skills agent.3md
search
files
json
commits
pr
fetch
research

route

Rank the skills whose triggers a request satisfies, best first, and show the load chain the top skill would pull in.

bun run cli route agent.3md "find every TODO in the tree"
request: "find every TODO in the tree"
  -> search  (score 1; matched: find)
  loads: search

The score is the number of distinct trigger phrases matched; the loads: line is the top skill plus its transitive dependencies.

get

Fetch one skill's full body by name (progressive disclosure: load only this plane). The header line shows its z, cost, bound command, and typed inputs.

bun run cli get agent.3md search
# search  (z=1, tool=rg --line-number {pattern} {path}, inputs=pattern:string, path:string)
# Skill: search

Find code by regex. Reach for this before opening files by hand. Fill {pattern}
(the regex) and {path} (a file or directory), then run.

resolve

Fetch a skill plus its transitive dependency chain (following [[z=N]] links), each plane once.

bun run cli resolve agent.3md pr
pr loads 2 plane(s):
  - pr  (-> 4)
  - commits

Here pr depends on the skill at z=4 (commits), so resolving pr brings both.

run

The full loop in one command: route the request, fill the chosen skill's command from k=v inputs, and print it. Free-text words form the request; name=value pairs fill inputs.

bun run cli run agent.3md "find every TODO" pattern=TODO path=src
request: "find every TODO"
  -> search  (matched: find)
  command: rg --line-number 'TODO' 'src'

If a placeholder has no value, the command is printed with it still visible and a fill: line names what is missing:

  command: rg --line-number {pattern} {path}
  fill:    pattern= path=

For a guidance-only skill (no tool), run prints the skill body instead of a command:

request: "research the web for docs"
  -> research  (matched: research, web, docs)
  (no command bound; this skill is guidance only)

# Skill: research
...

run --exec

Add --exec to execute the produced command (via the shell). Every referenced placeholder must have a value, or --exec refuses:

bun run cli run agent.3md "find every TODO" pattern=TODO path=src --exec
  command: rg --line-number 'TODO' 'src'
  --- exec ---
<command output here>

validate

Check that a file conforms to agent3md/1. Exits non-zero on any error, so it drops into CI directly.

bun run validate agent.3md
agent3md validate: agent.3md
  PASS - 0 error(s), 0 warning(s)

See Conformance and spec for every rule the validator checks.

The Rust equivalent

The native binary mirrors these commands one-to-one:

agent3md manifest agent.3md
agent3md route agent.3md "find every TODO"
agent3md get agent.3md search
agent3md resolve agent.3md pr
agent3md run agent.3md "find every TODO" pattern=TODO path=src --exec
agent3md validate agent.3md

See Loaders for the library APIs behind the CLI.