Cette page n’est pas encore traduite.

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 an instruction:// address. Where a command reads a text, the address may name a ref or a version: instruction://acme/support-agent@stable, @latest, @v2, @ver_…, or instruction://ins_…/draft for 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.
  • --help or -h anywhere 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:

instruction --help
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
Shell
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

CodeMeaning
0done
1error
2usage or a refused input
3transport or not signed in
4not found
5forbidden
6nothing applied
7not 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

CommandWhat the help says it does
instruction validatecheck documents: errors fail (exit 1), warnings are shown and pass — --strict fails on warnings too
instruction fmtconservative formatter (prints, or rewrites with --write)
instruction deliverthe 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 treethe authored tree (instruction/1) as JSON
instruction digestthe authored digest: SHA-256 of the file's bytes
instruction initscaffold a new instruction file
instruction renderHTML for the document (declarative shadow DOM; --full for a page)
instruction testrun the specification's conformance vectors in <dir> (source-cases.json, model-cases.json, resolution-cases.json, text/)
instruction evalrun the document's eval cases against Claude with your own credentials (ANTHROPIC_API_KEY or `ant auth login`)
instruction loginsign 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 whoamiwho the server says you are, and your organizations
instruction mcpa 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 listthe instructions you can see, 20 at a time (--all includes templates; --full, each whole in --json)
instruction getits details: latest version, draft, refs, counts
instruction pullthe 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 pushcreate one, or replace the draft of ID; --publish releases it (a new one is private unless --visibility says otherwise)
instruction publishrelease 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 deletemove it to the trash (30 days), or delete it for good
instruction versionsits versions, newest first (the last 200)
instruction revokerevoke a version (move refs off it first; followers hold)
instruction diffa unified diff (versions, refs or draft; default latest draft)
instruction refslist, move or delete refs, with their gates set a ref's gates (all of them: what isn't named is off)
instruction checksrun the checks on the draft (or a version); exit 1 when they fail
instruction forka copy of your own (default your personal workspace)
instruction exportinstruction.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 keygenmake an Ed25519 key pair (private, mode 0600)
instruction keysthe organization's publisher keys
instruction connectMCP 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 agentsagent credentials; a secret is shown once
instruction watchfollow 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 reportreport an applied version
instruction auditthe audit trail (last 100), or the whole filtered export

Offline commands

These need no account and no network.

instruction validate

Synopsis
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
Example
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

Synopsis
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.

Example
instruction fmt support-agent.md --write

Exits 0, or 2 with no file.

instruction deliver

Synopsis
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
Example
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

Synopsis
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.

Example
instruction tree support-agent.md > support-agent.tree.json

instruction digest

Synopsis
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.

Example
instruction digest support-agent.md

instruction init

Synopsis
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
Example
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

Synopsis
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
Example
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

Synopsis
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 (or source/cases.json): each source is valid or not, by the reader. A missing extension is not counted as an error.
  • resolution-cases.json (or resolution/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 with text/<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.

Example
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

Synopsis
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}
Example
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

Synopsis
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
Example
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

Synopsis
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>.

Example
instruction whoami --json

Finding and reading

instruction list

Synopsis
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
Example
instruction list --owner acme --query refund --limit 50

instruction get

Synopsis
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.

Example
instruction get acme/support-agent

Exits 4 when there is no such instruction, or you can't see it.

instruction pull

Synopsis
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.

Example
instruction pull acme/support-agent@stable --delivered --out current.md

instruction versions

Synopsis
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.

Example
instruction versions acme/support-agent

instruction diff

Synopsis
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.

Example
instruction diff acme/support-agent stable draft

Writing and releasing

instruction push

Synopsis
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
Example
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

Synopsis
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
Example
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

Synopsis
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
Example
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

Synopsis
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.

Example
instruction checks acme/support-agent

instruction revoke

Synopsis
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.

Example
instruction revoke acme/support-agent <ver_… id> --reason "Leaked a customer's address" --yes

instruction delete

Synopsis
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.

Example
instruction delete acme/old-agent
instruction delete acme/old-agent --purge --yes

instruction fork

Synopsis
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
Example
instruction fork acme/support-agent@stable --into <your org> --name support-agent-eu

Export and audit

instruction export

Synopsis
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.

Example
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

Synopsis
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
Example
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

Synopsis
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}
Example
instruction keygen --out acme-key.json --kid acme-2026

instruction keys

Synopsis
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.

Example
instruction keys --org acme list
instruction keys --org acme add acme-key.json --label "release laptop"

Connecting and following

instruction connect

Synopsis
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
--hostApp
genericAny MCP client
claudeClaude (claude.ai / Desktop)
chatgptChatGPT
claude-codeClaude Code
codexCodex
cursorCursor
vscodeVS Code
copilotGitHub Copilot CLI
gemini-cliGemini CLI
antigravityAntigravity
opencodeOpenCode
kiloKilo Code
qwen-codeQwen Code
droidFactory Droid
devinDevin
clineCline
kiroKiro
junieJetBrains Junie
crushCrush
gooseGoose
aiderAider
agentdagentd
sdkTypeScript SDK
ciCI / curl
Example
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

Synopsis
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:

instruction --help
--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.

Example
instruction watch acme/support-agent@stable --out AGENTS.md --block --require-signature

Following explains refs, holds and the follow file.

instruction bindings report

Synopsis
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.

Example
instruction bindings report acme/support-agent --version <ver_… id>

instruction mcp

Synopsis
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
Example
instruction mcp --root . --follow acme/support-agent@stable

Agent credentials

instruction agents

Synopsis
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).

Example
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.

Shell
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.

Last checked against the product:

Was this page helpful? Report a problem