instruction command reference
For developers who script the instruction command (the npm package instruction.md, 0.11.2): every command, its synopsis, its flags and their defaults, one example, and how it exits. Installing, signing in and how versions are signed are on The instruction CLI.
Each synopsis on this page is read from the CLI's own help (instruction --help) when the docs are built, so it is the one the installed version prints.
Reading a synopsis
<file>,<id>,<uri>: an argument you must give.[x]: one you may leave out.a|b: one of the words....: as many as you like.<id>and<uri>take an instruction's id (ins_…),owner/name, or aninstruction://address. Where a command reads a text, the address may name a ref or a version:instruction://acme/support-agent@stable,@latest,@v2,@ver_…, orinstruction://ins_…/draftfor the draft. Without a selector it reads the instruction's default ref.- Flags go anywhere on the line. A flag that takes a value takes the next word.
--helpor-hanywhere prints the help and does nothing else.
Common flags
Every registry command (all but the offline ones, keygen and login) takes these. The help says:
Common flags: --json (machine output), --yes (agree to what a release, revoke or ref move asks first; needed without a terminal), --url, --token (or INSTRUCTION_MD_TOKEN). | Flag | Default | What it does |
|---|---|---|
--json |
off | Prints the result as JSON on stdout instead of lines. Questions and notes still go to stderr |
--yes, -y |
off | Agrees to whatever the command asks first (a release, a ref move, a revoke, a delete). Without a terminal and without it, nothing changes: exit 7 |
--url <mcp url> |
INSTRUCTION_MD_URL, else the server you last signed in to, else https://instruction.md/mcp |
The MCP server |
--token <bearer> |
INSTRUCTION_MD_TOKEN, else your stored sign-in |
A token used as it is, never refreshed and never upgraded to org:admin |
instruction publish acme/support-agent --yes --json \
--url https://instruction.md/mcp --token "$INSTRUCTION_MD_TOKEN" A command that asks first prints what will happen, then Go ahead? [y/N] on a terminal. Anything but y or yes cancels it (exit 7).
Exit codes
| Code | Meaning |
|---|---|
0 | done |
1 | error |
2 | usage or a refused input |
3 | transport or not signed in |
4 | not found |
5 | forbidden |
6 | nothing applied |
7 | not confirmed |
A server error is printed as tool: code: message. The code invalid_input exits 2, unauthenticated 3, not_found 4 and forbidden 5; any other code exits 1. A request that fails on the way (the network, a 401) exits 3. Exit codes says what to do about each.
Every command
| Command | What the help says it does |
|---|---|
instruction validate | check documents: errors fail (exit 1), warnings are shown and pass — --strict fails on warnings too |
instruction fmt | conservative formatter (prints, or rewrites with --write) |
instruction deliver | the text a model receives (instruction-text/1), its bases and includes read from files beside it; --resolved prints the resolved artifact (instruction-resolved/1) |
instruction tree | the authored tree (instruction/1) as JSON |
instruction digest | the authored digest: SHA-256 of the file's bytes |
instruction init | scaffold a new instruction file |
instruction render | HTML for the document (declarative shadow DOM; --full for a page) |
instruction test | run the specification's conformance vectors in <dir> (source-cases.json, model-cases.json, resolution-cases.json, text/) |
instruction eval | run the document's eval cases against Claude with your own credentials (ANTHROPIC_API_KEY or `ant auth login`) |
instruction login | sign in, in your browser; --device: with a code on another device (over SSH, in a container); --admin: with permission to administer your organizations (keys, agents, the audit ask for it when they need it) |
instruction whoami | who the server says you are, and your organizations |
instruction mcp | a stdio MCP server for an agent in your editor: the instruction files in the workspace and the language's tools, and — signed in, unless --local — the registry on the same connection; --follow (default: .instruction/follow.json's) also serves that instruction as instruction://current and the prompt "follow" |
instruction list | the instructions you can see, 20 at a time (--all includes templates; --full, each whole in --json) |
instruction get | its details: latest version, draft, refs, counts |
instruction pull | the text at a ref or version (instruction://{id}@latest, @v2, @ver_…, owner/name, or {id}/draft); --meta prints its _meta; --delivered: the text a model receives, not the source |
instruction push | create one, or replace the draft of ID; --publish releases it (a new one is private unless --visibility says otherwise) |
instruction publish | release the draft as the next version (moves latest, unless --refs names others or --quiet moves none); the first one needs --visibility: who can read it |
instruction delete | move it to the trash (30 days), or delete it for good |
instruction versions | its versions, newest first (the last 200) |
instruction revoke | revoke a version (move refs off it first; followers hold) |
instruction diff | a unified diff (versions, refs or draft; default latest draft) |
instruction refs | list, move or delete refs, with their gates set a ref's gates (all of them: what isn't named is off) |
instruction checks | run the checks on the draft (or a version); exit 1 when they fail |
instruction fork | a copy of your own (default your personal workspace) |
instruction export | instruction.md + version.json every version with its record (zip), or an OCI image layout (tar, one manifest per version) for oras cp --from-oci-layout |
instruction keygen | make an Ed25519 key pair (private, mode 0600) |
instruction keys | the organization's publisher keys |
instruction connect | MCP host config snippets (with an issued agent's client id); HOST: claude, chatgpt, claude-code, codex, cursor, vscode, copilot, gemini-cli, antigravity, opencode, kilo, qwen-code, droid, devin, cline, kiro, junie, crush, goose, aider, agentd, sdk, ci, generic |
instruction agents | agent credentials; a secret is shown once |
instruction watch | follow a ref (keep-last-good, reports applied versions); --out writes the delivered text whole or not at all, --block only its own region of the file; --rule a Cursor rule always applied (--out .cursor/rules/instruction-md.mdc); without <uri>, the project's .instruction/follow.json; --lines: one line per new version on stdout (a plugin monitor); without --keys the publisher's keys.json is discovered. --block targets, live first: ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md (re-read before each model request), ~/.gemini/GEMINI.md (Gemini CLI, Antigravity), ~/.copilot/copilot-instructions.md, ~/.qwen/QWEN.md, ~/.config/kilo/AGENTS.md, ~/.junie/AGENTS.md, ~/.config/amp/AGENTS.md, ~/.agents/AGENTS.md (Cline), ~/.pi/agent/AGENTS.md, ~/.config/zed/AGENTS.md (each read when a session starts) |
instruction bindings report | report an applied version |
instruction audit | the audit trail (last 100), or the whole filtered export |
Offline commands
These need no account and no network.
instruction validate
instruction validate <file...> [--json] [--strict] [--quiet] Checks each file with the specification's reader and inline checks, and reports a line in the older Specification 1.1 syntax as an error. Each file gets one line: ok, WARNED (warnings only) or INVALID, followed by each problem with its line and its code in brackets.
| Flag | Default | Effect |
|---|---|---|
--strict |
off | A warning fails the file too |
--quiet |
off | Shows errors only, not warnings or notes |
--json |
off | A JSON array with one object per file: file, ok, spec, digest (the authored digest) and diagnostics |
instruction validate support-agent.md --strict Exits 1 when any file has an error (or, with --strict, a warning), and 2 with no file. Diagnostics lists the codes.
instruction fmt
instruction fmt <file...> [--write] The conservative formatter: line endings, one final newline, and no trailing whitespace on a directive's own lines. Prose, code, structured bodies and front matter are left as written. It prints the result; --write rewrites each file instead, and prints formatted <file> only for a file that changed.
instruction fmt support-agent.md --write Exits 0, or 2 with no file.
instruction deliver
instruction deliver <file> [name=value ...] [--resolved] Prints the text a model receives (instruction-text/1). Bases (extends) and includes are read from files under the file's own folder, never above it and never from a URL. Each name=value is a parameter, read as the document declares it: size=3 is a number where size is an integer, tags=a,b a list, on=true a boolean.
| Flag | Default | Effect |
|---|---|---|
--resolved |
off | Prints the resolved document (instruction-resolved/1) as JSON, with its digest, instead of the text |
instruction deliver support-agent.md environment=production Errors, such as a required parameter without a value, go to stderr, print nothing on stdout and exit 1. Warnings go to stderr and the text is still printed. Delivery describes the text.
instruction tree
instruction tree <file> Prints the authored tree (instruction/1) as JSON. It exits 1 when the reader found an error; the tree is still printed.
instruction tree support-agent.md > support-agent.tree.json instruction digest
instruction digest <file> Prints the authored digest, sha256: and the hex SHA-256 of the file's bytes. It is the digest a release records as the version's authored digest.
instruction digest support-agent.md instruction init
instruction init [name] [--template minimal|agent] Writes a new instruction file and prints created <file>. The name defaults to instruction, and .md is added when it is missing. The title is made from the file name: dashes and underscores become spaces, and each word starts with a capital.
| Flag | Default | Effect |
|---|---|---|
--template |
minimal |
minimal: one rule of each kind and a guardrail. agent: a required parameter, an identified rule, a conditional rule, a person who approves, the reply's shape, context and a glossary |
instruction init support-agent --template agent Exits 2 when the file exists or the template is unknown. Quickstart: the CLI shows the agent template.
instruction render
instruction render <file> [--view rendered|delivered|source] [--theme light|dark|auto]
[name=value ...] [--full] [--script URL] Prints the document as HTML in a declarative shadow DOM, for a static site. name=value gives parameters, as for deliver.
| Flag | Default | Effect |
|---|---|---|
--view |
rendered |
rendered, delivered (the text a model receives) or source |
--theme |
auto |
light, dark or auto |
--full |
off | A whole HTML page instead of an element |
--script <url> |
none | With --full: the renderer's script the page loads |
instruction render support-agent.md --full --theme light environment=staging > support-agent.html Exits 1 when the document has an error, 2 for a --view it doesn't know. Embed covers the renderer on a page.
instruction test
instruction test <dir> Runs the specification's conformance vectors in a folder, for checking a reader of your own against this one. The package carries a copy at dist/spec/specification/conformance inside its install folder. It runs:
source-cases.json(orsource/cases.json): each source is valid or not, by the reader. A missing extension is not counted as an error.resolution-cases.json(orresolution/cases.json): each tree resolves, or fails with the expected code, and makes the expected changes.text/<case>.json: the text profile of each tree, compared byte for byte withtext/<case>.txt.
It prints ok or FAIL per case and N passed, M failed. It does not run model-cases.json, policy-cases.json or workflow-cases.json, and says nothing about them.
instruction test "$(npm root -g)/instruction.md/dist/spec/specification/conformance" Exits 1 when a case fails, 2 when the folder has none of the three kinds.
instruction eval
instruction eval <file> [--case NAME] [--model ID] [--judge-model ID] [--dry-run] [--json] Runs the document's :::eval cases against Claude, with your own credentials: ANTHROPIC_API_KEY, or a profile from ant auth login. This runner is the adapter instruction.md/claude. It runs a case that names that adapter or none, and skips one for another adapter with a line on stderr. Each case is sent with the same text a release would deliver.
| Flag | Default | Effect |
|---|---|---|
--case <name> |
every case | One case, by name or suite/name |
--model <id> |
claude-opus-5 |
The model that answers |
--judge-model <id> |
the --model |
The model that grades the answers |
--dry-run |
off | Prints what each case would send (system and user text) and calls no model |
--json |
off | {file, results, problems} |
instruction eval support-agent.md --dry-run
ANTHROPIC_API_KEY=<key> instruction eval support-agent.md --case refunds/over-limit --json Prints PASS or FAIL per case, each failed assertion, and N passed, M failed. Exits 1 when a case fails, the document has an error, or an eval block has a problem. A document with no case for this runner exits 0. Checks, evals and tests explains how cases are written.
instruction --version
Prints instruction.md {ref.cliVersion} (instruction/{ref.specEdition}): the package, its version and the language edition it reads. -v is the same.
Signing in
instruction login
instruction login [--device] [--admin] [--no-browser] [--url U] [--issuer I [--trust-issuer]] Signs you in and keeps the sign-in for the server. It prints Signed in to <url> as <name>.; --json prints {url, me, admin}.
| Flag | Default | Effect |
|---|---|---|
--device |
off | A code to approve on another device, for a machine with no browser |
--admin |
off | Asks for the org:admin scope too: publisher keys, agent credentials, the audit |
--no-browser |
off | Prints the link and doesn't open a browser |
--url <mcp url> |
INSTRUCTION_MD_URL, else https://instruction.md/mcp |
The server to sign in to. It becomes the default server for every command |
--issuer <url> |
INSTRUCTION_MD_ISSUER, else the one the server names |
The sign-in service. When it isn't the server's own, the CLI asks first |
--trust-issuer |
off | Goes ahead with --issuer where there is no terminal to ask on |
--client <id> |
instruction-cli |
The OAuth client the sign-in uses. Not in the help |
instruction login --device --admin Exits 3 on a timeout or when the sign-in service can't be reached, 2 for an address or sign-in service it refuses, and 7 when you deny the consent or answer no. Sign in has the details.
instruction whoami
instruction whoami Prints who the server says you are, the kind of account, and your organizations with your role, personal for your own, and the plan. Not signed in, it prints anonymous at <url>.
instruction whoami --json Finding and reading
instruction list
instruction list [--owner O] [--query Q] [--all] [--limit N] [--cursor C] [--full] One line per instruction: owner/name, visibility, the latest version (or draft), the id and the title.
| Flag | Default | Effect |
|---|---|---|
--owner <slug> |
all | Only an organization's |
--query <words> |
none | Words in names, titles, descriptions, tags and published text |
--all |
off | Templates too |
--limit <n> |
20 (the server's) | How many, at most 200 |
--cursor <c> |
none | The next page: the last line says (more: --cursor …) when there is one |
--full |
off | Every field of each, for --json |
instruction list --owner acme --query refund --limit 50 instruction get
instruction get <uri|id> Its address, title, visibility, kind and your role; the latest version; the draft's revision, whether it changed since the latest version, and its pending suggestions and open comments; the refs; and the counts of versions, followers and open proposals.
instruction get acme/support-agent Exits 4 when there is no such instruction, or you can't see it.
instruction pull
instruction pull <uri> [--out FILE] [--meta] [--delivered] Prints the authored text at a ref or version, which is what an edit and push take.
| Flag | Default | Effect |
|---|---|---|
--out <file> |
stdout | Writes the file whole or not at all, and says <file> ← v2 ver_… (stable) on stderr |
--delivered |
off | The text a model receives, with its bases and includes read from the registry |
--meta |
off | Also prints the read's _meta (version, ref, digest, signature) as JSON on stderr |
With --json it prints {uri, meta, _meta, text}, or file instead of text with --out.
instruction pull acme/support-agent@stable --delivered --out current.md instruction versions
instruction versions <id> The last 200 versions, newest first: the version, its id, the refs on it, when, who released it, signed, unsigned or REVOKED, and its message.
instruction versions acme/support-agent instruction diff
instruction diff <id> [from] [to] A unified diff between two texts: versions by id or number, refs, or draft. from defaults to latest and to to draft. The first line is from → to: +N −M line(s), or no change.
instruction diff acme/support-agent stable draft Writing and releasing
instruction push
instruction push <file> [--to ID] [--name N] [--title T] [--visibility private|internal|public] [--org SLUG]
[--suggest] [--publish [--message M]] Without --to, creates an instruction from the file. With --to, replaces that instruction's draft, at the revision it has now. It prints draft saved: owner/name revision N and the address.
| Flag | Default | Effect |
|---|---|---|
--to <id> |
none: a new one | The instruction whose draft it replaces. You must be able to edit or suggest (exit 5 otherwise) |
--name <name> |
the server's choice | A new one's name, the name in owner/name |
--title <title> |
the front matter's title |
A new one's title |
--org <slug> |
your personal organization | Where a new one goes |
--visibility |
private for a new one |
private, internal or public. With --to and no --publish, it changes the visibility, and asks first |
--suggest |
off | The change lands as suggestions a Maintainer accepts |
--publish |
off | Releases the draft as the next version too, and asks first |
--message <text> |
none | With --publish: the version's message |
instruction push support-agent.md --org acme --visibility internal
instruction push support-agent.md --to acme/support-agent --publish --message "Tighter refund rule" --yes When the release fails or isn't confirmed, the draft is saved anyway, and the message says where. When the release wasn't confirmed (exit 7), it also says how to release it: instruction publish <id> --yes. --sign-with exits 2: see How versions are signed.
instruction publish
instruction publish <id> [--message M] [--refs a,b | --quiet] [--tag REF] [--visibility private|internal|public] Releases the draft as the next version, and asks first. It prints published owner/name vN (ver_…) → latest and the address; a version that moves no ref says no ref (a quiet version).
| Flag | Default | Effect |
|---|---|---|
--refs a,b |
the default ref, latest |
The refs the version moves |
--quiet |
off | Moves no ref: a quiet version |
--tag <ref> |
none | Moves this ref too, with latest or with the --refs you named |
--visibility |
the instruction's | private, internal or public. The first version needs it (exit 2 without it) |
--message <text> |
none | The version's message |
instruction publish acme/support-agent --message "Tighter refund rule" --tag stable --yes Nothing makes a stable ref for you: create it with instruction refs <id> set stable <version>. A ref with gates refuses a move that doesn't meet them. --sign-with exits 2.
instruction refs
instruction refs <id> [set REF VER | delete REF]
instruction refs <id> gate REF [--require-checks] [--require-signature] [--promote-from R [--after MIN]] | Form | What it does |
|---|---|
refs <id> or refs <id> list |
Each ref, the version it points at, when it moved, and its gates |
refs <id> set REF VER |
Points REF at a version: ver_…, v3, or another ref. It makes the ref when it is new. It asks first when it moves the default ref, whose followers switch. This is how you roll back, and how you create stable |
refs <id> delete REF |
Deletes a ref other than latest and the default ref. Its followers keep their last version. See the note below for a ref with gates |
refs <id> gate REF … |
Sets the ref's gates, at the version the ref points at now. It replaces all of them: a gate you don't name is off. The ref must exist (exit 4 otherwise). It doesn't ask first: the gates change what may move the ref, not what its followers read. It needs the Admin role on the instruction (manage) |
The gate flags:
| Flag | Default | Effect |
|---|---|---|
--require-checks |
off | A version moves here only when its checks pass |
--require-signature |
off | A version moves here only when it is signed |
--promote-from <ref> |
none | The ref follows another ref |
--after <minutes> |
60 | With --promote-from: how long a version waits on that ref before it moves here |
instruction refs acme/support-agent
instruction refs acme/support-agent set stable <ver_… id> --yes
instruction refs acme/support-agent gate stable --require-checks --promote-from latest --after 120 --yes Exits 2 for a form it doesn't know. How instruction.md works explains what refs are for.
instruction checks
instruction checks <id> [--version V] Runs the server's checks on the draft, or on a version with --version. These are the checks a ref's --require-checks gate asks for. It prints whether they pass, then each check and its findings by line. Exits 1 when they fail; warnings are shown and pass.
instruction checks acme/support-agent instruction revoke
instruction revoke <id> <version> [--reason R] Revokes a version no ref points at, and asks first: move the refs off it first. The version stays readable, marked revoked. Refs can't move back to it, and agents pinned to it keep their last good version.
instruction revoke acme/support-agent <ver_… id> --reason "Leaked a customer's address" --yes instruction delete
instruction delete <id> [--purge] Moves the instruction to the trash, where it can be restored for 30 days, and asks first. --purge deletes it for good: it moves it to the trash first if it isn't there, then asks again.
instruction delete acme/old-agent
instruction delete acme/old-agent --purge --yes instruction fork
instruction fork <uri> [--into ORG|ws_…] [--name N] [--title T] Makes a copy of your own, from the version the address names (@v2, @stable) or the default ref. The copy has a draft and no versions yet.
| Flag | Default | Effect |
|---|---|---|
--into <org or ws_…> |
your personal workspace | An organization (its default workspace) or a workspace |
--name <name> |
the original's | The copy's name |
--title <title> |
the original's | The copy's title |
instruction fork acme/support-agent@stable --into <your org> --name support-agent-eu Export and audit
instruction export
instruction export <uri> [--dir D]
instruction export <id> --format zip|oci [--out FILE] Without --format, exports one version: instruction.md (its authored text) and version.json (its record) in --dir, . by default. The address names a version or a ref; without a selector it exports the version of the default ref. A draft address (instruction://ins_…/draft) exits 2.
With --format zip or --format oci, the server's worker exports every version. zip holds each version with its record. oci is an OCI image layout (a tar, one manifest per version) for oras cp --from-oci-layout. The CLI waits up to 3 minutes and writes the file to --out, or to --dir under the server's file name. A longer export exits 1; your notifications say when it is ready.
instruction export acme/support-agent@v3 --dir ./v3
instruction export acme/support-agent --format zip --out support-agent.zip Export covers the formats.
instruction audit
instruction audit [export] <id|uri> | --org ORG [--types a,b] [--from ISO] [--to ISO] [--self]
[--format ndjson|csv] [--out FILE] The audit trail of an instruction (<id|uri>) or an organization (--org): the last 100 records, one line each. export writes the whole filtered trail instead. It never includes content. Needs org:admin (see Administering an organization).
| Flag | Default | Effect |
|---|---|---|
--org <slug> |
none | The organization's trail |
--types a,b |
all | Only these event types: exact, or a family such as version.* |
--from, --to |
none | ISO 8601 times |
--self |
off | Only your own records. Not with export (exit 2) |
--format |
ndjson |
With export: ndjson or csv |
--out <file> |
stdout | With export: where the file goes |
instruction audit acme/support-agent
instruction audit export --org acme --types "version.*,ref.changed" --from 2026-11-01T00:00:00Z --format csv --out audit.csv Audit lists the event types.
Publisher keys
instruction keygen
instruction keygen [--out KEY.json] [--kid K] Makes an Ed25519 key pair offline and writes it as JSON (privateJwk, publicJwk), mode 0600. Keep the file offline.
| Flag | Default | Effect |
|---|---|---|
--out <file> |
instruction-key.json |
Where it goes. An existing file is refused (exit 1) |
--kid <id> |
cli- and 8 hex digits |
The key id: letters, digits, -, _, ., 1 to 64 (exit 2 otherwise) |
--force |
off | Overwrites --out |
--json |
off | {kid, file, publicJwk} |
instruction keygen --out acme-key.json --kid acme-2026 instruction keys
instruction keys [--org SLUG] [list | add KEY.json [--label L] | rotate | retire KID | revoke KID] The organization's publisher keys, published at instruction://pub/<org>/keys.json. Without --org, your personal organization. Each line is the key id, its state, its source, when it was made and its label.
| Form | What it does |
|---|---|
keys or keys list |
Lists them. The first release makes the platform key |
keys add KEY.json [--label L] |
Registers a key's public half (it never sends the private one) |
keys rotate |
Retires the active platform key and makes the next; new versions are signed with the new one |
keys retire KID |
Retires a key: past versions still verify, and no new version is signed with it. See the note below |
keys revoke KID |
Revokes a key: versions signed with it count as unsigned for ref and follower policies. Asks first |
Every form but list asks for org:admin when your sign-in lacks it; list needs it too, so sign in with --admin first. The server signs every version with the platform key; a key you add is listed but signs nothing. Signing and verification explains the states.
instruction keys --org acme list
instruction keys --org acme add acme-key.json --label "release laptop" Connecting and following
instruction connect
instruction connect [--host HOST] [--agent CLIENT_ID] [--org SLUG] [<uri>] Prints the configuration an app needs to reach the MCP server, for the instruction you name (instruction://<owner>/<name>@latest as a placeholder when you don't).
| Flag | Default | Effect |
|---|---|---|
--host <app> |
generic |
The app, from the table below (exit 2 for another) |
--agent <client id> |
none | An agent credential's client id (or its id): the snippet carries its client id and token URL, never its secret. Needs org:admin, as agents list does |
--org <slug> |
your personal organization | Where --agent is looked up |
--host | App |
|---|---|
generic | Any MCP client |
claude | Claude (claude.ai / Desktop) |
chatgpt | ChatGPT |
claude-code | Claude Code |
codex | Codex |
cursor | Cursor |
vscode | VS Code |
copilot | GitHub Copilot CLI |
gemini-cli | Gemini CLI |
antigravity | Antigravity |
opencode | OpenCode |
kilo | Kilo Code |
qwen-code | Qwen Code |
droid | Factory Droid |
devin | Devin |
cline | Cline |
kiro | Kiro |
junie | JetBrains Junie |
crush | Crush |
goose | Goose |
aider | Aider |
agentd | agentd |
sdk | TypeScript SDK |
ci | CI / curl |
instruction connect --host cursor acme/support-agent@stable With --with-hooks, --write or --managed, the line is handed to instruction agents follow: see instruction-agents command reference. Connect an MCP client explains the snippets.
instruction watch
instruction watch [<uri>] [--pinned] [--freshness S] [--out FILE [--block | --rule]] [--lines] [--label L] [--no-report]
[--require-signature [--keys FILE] [--publisher URL]] [--require-delivery-signature] [--once] Follows a ref and applies each new version, keeping the last good one when a read fails or a version doesn't pass. It reports each version it applied, so the instruction's followers show it. Without <uri>, it follows what the project's .instruction/follow.json names, takes that file's requireSignature, and keeps .instruction/current.md for the hooks. Ctrl-C stops it.
| Flag | Default | Effect |
|---|---|---|
--pinned |
off | Stays on the version it starts on |
--freshness <s> |
60 | Seconds between reads when no live update comes |
--out <file> |
none | Writes the delivered text there, whole or not at all |
--block |
off | With --out: only its own region of the file; the rest is left as it is |
--rule |
off | With --out, not --block: a Cursor rule that is always applied (.cursor/rules/instruction-md.mdc) |
--lines |
off | One line per new version on stdout, nothing else there: for an app's monitor. In a project that follows nothing, it exits 0 at once |
--label <name> |
instruction-cli@<host name> |
The follower's name in the reports |
--no-report |
off | Reports nothing |
--require-signature |
off | Applies only versions whose signature verifies |
--keys <file> |
the publisher's keys.json |
The keys to verify with |
--publisher <url> |
discovered | Where the publisher's keys are |
--require-delivery-signature |
off | Also requires the server's signature on the delivered text |
--once |
off | Reads once, applies, and exits: 0, or 6 when nothing could be applied |
Without --out, a project, --lines or --json, it prints the first version's text on stdout. Each version applied is a line, <time> applied v3 ver_… (stable) ← ver_… [signature verified] → <file>, and a hold is hold: <reason> (keeping ver_…) on stderr. With --json each is a JSON line.
The help names the files --block suits, and when each app reads its file:
--block targets, live first:
~/.codex/AGENTS.md,
~/.config/opencode/AGENTS.md (re-read before each model request),
~/.gemini/GEMINI.md (Gemini CLI, Antigravity),
~/.copilot/copilot-instructions.md,
~/.qwen/QWEN.md,
~/.config/kilo/AGENTS.md,
~/.junie/AGENTS.md,
~/.config/amp/AGENTS.md,
~/.agents/AGENTS.md (Cline),
~/.pi/agent/AGENTS.md,
~/.config/zed/AGENTS.md (each read when a session starts) The organization's plan sets how many agents or apps get live updates at once:
Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
. Reads are never limited. When others already hold every place the plan gives,watch says live updates are taken: … Still reading on schedule. once, and goes on reading every --freshness seconds. See Live updates.
instruction watch acme/support-agent@stable --out AGENTS.md --block --require-signature Following explains refs, holds and the follow file.
instruction bindings report
instruction bindings report <id> --version VER [--binding SUB] Tells the server which version you applied, for a follower you run yourself. --binding names the binding when you have more than one. It prints the version reported and, when there is a newer one, behind.
instruction bindings report acme/support-agent --version <ver_… id> instruction mcp
instruction mcp [--root DIR ...] [--local] [--follow URI] A stdio MCP server for an agent in your editor. It serves the instruction files in the workspace and the language's tools. Signed in, and unless --local, it serves the registry's tools on the same connection; a registry it can't reach leaves the workspace's tools, with a note on stderr.
| Flag | Default | Effect |
|---|---|---|
--root <dir> |
the client's roots, else the current folder | A workspace folder; give it more than once for more |
--local |
off | The workspace only, without the registry |
--follow <uri> |
.instruction/follow.json's |
Also serves that instruction as instruction://current and the prompt follow |
instruction mcp --root . --follow acme/support-agent@stable Agent credentials
instruction agents
instruction agents [--org SLUG] [list | create NAME [--kind agent|service] [--scopes read,write,publish] [--workspace-role R]
| rotate ID | revoke ID] The organization's agent credentials (API keys): accounts that sign in with a client id and secret, for an agent, a service or a pipeline. Without --org, your personal organization.
| Form | What it does |
|---|---|
agents or agents list |
Each credential: its id, kind, name, scopes and state |
agents create NAME |
Makes one, and prints its client_id, its client_secret (shown once: store it now), its token_url, and its audience and scopes |
agents rotate ID |
A new secret, shown once; the old one stops working at once. Asks first |
agents revoke ID |
No new tokens; the ones it holds expire within five minutes. Asks first |
| Flag | Default | Effect |
|---|---|---|
--kind |
agent |
agent or service |
--scopes read,write,publish |
the server's | What it may do. A short name becomes instructions:<name>; a name with : is used as it is |
--workspace-role <role> |
none | Its role in the default workspace: reader, contributor, maintainer or admin |
Every form but list asks for org:admin when your sign-in lacks it; list needs it too (the server offers the organization's tools only to a token with it), so sign in with --admin first. After instruction agents, the words hook, acp, turn, sync, fleet, apply, doctor, accounts, credential, signin, follow, install, run, check, connect, login, whoami, mcp, help are not this command: they go to @instruction.md/agents (next section).
instruction agents --org acme list
instruction agents --org acme create triage-bot --kind agent --scopes read --workspace-role reader Agent credentials and CI tokens shows how an agent gets a token with them.
Handed to @instruction.md/agents
instruction agents <command> runs the agents' package with the rest of the line: instruction-agents when it is on your PATH, else npx --yes @instruction.md/agents. Its output and exit code are the agents' command's own. When it can't be started, the CLI says how to install it and exits 1, or 0 for hook and turn, which never break a prompt.
instruction agents follow acme/support-agent --host claude-code --write
# is the same as
instruction-agents follow acme/support-agent --host claude-code --write
npx -y @instruction.md/agents follow acme/support-agent --host claude-code --write The commands that moved out of this package still work under their old top-level names, handed over the same way: instruction hook, instruction acp, instruction turn, instruction sync, instruction fleet, instruction apply, instruction doctor, instruction accounts, instruction credential, instruction signin, and instruction connect with --with-hooks, --write or --managed. Each prints a one-line note on stderr first, except hook, turn, credential. instruction-agents command reference has every one.