Quickstart: the CLI
For developers who want the whole loop in a terminal: write an instruction, check it offline, release it, give it a stable ref, and follow that ref the way an agent does. It takes about ten minutes.
What you'll make
A private instruction, <you>/support-agent, with two versions. A stable ref points at the version you choose. A running instruction watch keeps current.md equal to the text an agent following stable receives, and rewrites it when you move stable.
What you need
- Node.js 20.19 or later, and npm.
- A terminal. Steps 1 to 3 work offline, with no account.
- An instruction.md account for steps 4 to 9. You sign in with a passkey; see Sign in.
Plans Community 3 · Pro 100 · Team 1,000 · Enterprise unlimited
This tutorial makes one private instruction. It counts against your plan's private instructions until you delete it in Clean up.
Steps
Install the CLI
Shellnpm i -g instruction.md instruction --versionIt prints its version and the edition of the language it reads:
Outputinstruction.md 0.11.2 (instruction/1)The package is
instruction.md; the command it installs isinstruction. To run it once without installing, putnpx instruction.mdwhere this page writesinstruction.Scaffold an instruction
Shellinstruction init support-agent --template agentOutputcreated support-agent.mdinittakes a name (.mdis added) and--template minimal(the default) or--template agent. It refuses to overwrite a file that exists. Theagenttemplate writes this:support-agent.md--- spec: "1" title: Support Agent parameters: environment: { type: enum, values: [staging, production], source: workspace, required: true } --- # Support Agent You operate in ${environment}. Describe your purpose in two sentences. ## Rules MUST[confirm-irreversible]: confirm before any irreversible action. BECAUSE: an undo is not always possible, and the human owns the decision. SHOULD: prefer the smallest change that solves the problem. NEVER: reveal credentials or another customer's data. MAY: skip confirmation for read-only actions. MUST (if the environment is production): confirm every write with a person first; real users see it. ::person{id=owner title="The owner" role=approver} :::output{response-format=markdown title="Every reply"} What you did, what you did not do, and what happens next. ::: :::context{title="Where things are"} Describe the systems the agent touches and how they relate. ::: :::glossary Term : Define the words the agent must use precisely. :::Its front matter declares one parameter,
environment, which is required and is one ofstagingorproduction.MUST[confirm-irreversible]gives the rule an id that stays the same when you reword it. TheMUST (if …)rule applies only when its condition holds. The::personand:::output,:::context,:::glossaryblocks are delivered under headings that name their kind. Rules and blocks lists every keyword and kind.Check it, and see what an agent receives
Shellinstruction validate support-agent.md instruction fmt support-agent.md --writeOutputok support-agent.mdvalidatereports what a release would refuse. Errors exit 1 and printINVALID; warnings printWARNEDand pass unless you add--strict.--jsonprints each file's diagnostics and its authored digest.fmtprints the formatted text; with--writeit rewrites the file and saysformatted <file>only when something changed.Now ask for the delivered text without the required parameter:
Shellinstruction deliver support-agent.md echo $?Outputline 1: ${environment} is required and has no value [parameter-missing] 1deliverprints nothing on stdout and exits 1 when a required parameter has no value. Give it asname=value:Shellinstruction deliver support-agent.md environment=stagingOutput# Support Agent You operate in staging. Describe your purpose in two sentences. ## Rules MUST: confirm before any irreversible action. BECAUSE: an undo is not always possible, and the human owns the decision. SHOULD: prefer the smallest change that solves the problem. NEVER: reveal credentials or another customer's data. MAY: skip confirmation for read-only actions. MUST (if the environment is production): confirm every write with a person first; real users see it. ### person: The owner Attributes: {"role":"approver"} ### output: Every reply Attributes: {"response-format":"markdown"} What you did, what you did not do, and what happens next. ### Context: Where things are Describe the systems the agent touches and how they relate. ### glossary: glossary Term : Define the words the agent must use precisely.This is what a model receives (instruction-text/1). The front matter is gone,
${environment}is filled in, and the rule id is not delivered. A value outside the enum is refused the same way:Output for environment=prodline 1: the value given for ${environment} is not a valid enum (staging, production) [parameter-invalid]--resolvedprints the resolved form as JSON instead. What an agent receives defines both.Sign in
Shellinstruction login # on a machine without a browser (SSH, a container): a code you enter on another device instruction login --deviceinstruction loginopens your browser.--deviceshows a code to enter on another device instead. When it finishes:OutputSigned in to https://instruction.md/mcp as <Your Name> (@<you>) <you@example.com>.The sign-in is kept in
~/.config/instruction-md/credentials.json(mode 0600, underXDG_CONFIG_HOMEwhen set) and refreshed as it runs out.instruction agents loginuses the same sign-in. For CI, use a token instead: Agent credentials.Push the draft
Shellinstruction push support-agent.md --visibility privateOutputdraft saved: <you>/support-agent revision 1 instruction://<id>pushwithout--tocreates an instruction from the file, in your personal workspace (--org <slug>for another organization). Its name comes from the title (support-agent, with a number added if you have one already) unless you pass--name. It holds a draft and no version yet. Note the id it prints (ins_…): the next steps take it as<id>.owner/nameworks too.Release the first version
Shellinstruction publish <id> --visibility private --message "First version"A release moves the default ref,
latest, so the server asks first. The CLI prints what it asks and waits fory:OutputRelease v1 of Support Agent as latest? 0 agent(s) following latest switch to v1. Its versions can be read by you and the people you share it with. Go ahead? [y/N] y published <you>/support-agent v1 (ver_<v1>) → latest instruction://<id>The first release must say who reads it, with
--visibility, even when the instruction was created private. Every version is signed by the server with your organization's publisher key; there is nothing to set up. See Signing and verification.Without a terminal (CI, a script), add
--yes. Without it the CLI changes nothing and exits 7.Shell, no terminalinstruction publish <id> --message "First version" --visibility private --yesCreate the stable ref
stableis never created for you. Point it at v1:Shellinstruction refs <id> set stable v1 instruction refs <id>Outputstable → v1 (ver_<v1>) latest → v1 ver_<v1> <time> stable → v1 ver_<v1> <time>latestmoves on every release that doesn't name other refs (--refs,--quiet).stablemoves only when you move it. It isn't the default ref, so moving it asks nothing. A ref can also carry gates, such as passing checks or a timed promotion fromlatest: see Refs.Follow stable as an agent does
In a second terminal, in an empty folder:
Shellinstruction watch instruction://<id>@stable --out current.mdOutput<time> applied v1 ver_<v1> (stable) → current.md watching instruction://<id>@stable (freshness 60s, follow); Ctrl-C to stopwatchreads the versionstablepoints at, writes its delivered text tocurrent.mdwhole or not at all, and reports the applied version to the server, so the instruction now has a follower. It hears of a new version through a live update, and reads again every 60 seconds either way (--freshness). Leave it running.Plans Community 1 · Pro unlimited · Team unlimited · Enterprise unlimited
When your plan's live updates are taken by another agent or app,
watchprintslive updates are taken: … Still reading on schedule.and keeps reading every 60 seconds. Live updates explains the limit.Release v2 and move stable
In
support-agent.md, change theSHOULDline to:support-agent.mdSHOULD: prefer the smallest change that solves the problem, and say what you left out.Then, in the first terminal:
Shellinstruction push support-agent.md --to <id> instruction publish <id> --message "Say what was left out" instruction refs <id> set stable v2Outputdraft saved: <you>/support-agent revision 2 instruction://<id> Release v2 of Support Agent as latest? 0 agent(s) following latest switch to v2. Go ahead? [y/N] y published <you>/support-agent v2 (ver_<v2>) → latest instruction://<id> stable → v2 (ver_<v2>)push --to <id>replaces the draft. The release moveslatest, and nobody followslatest, so the follower count is 0. The watcher keeps v1 untilstablemoves. Afterrefs … set stable v2, the watcher prints:Output, second terminal<time> applied v2 ver_<v2> (stable) ← ver_<v1> → current.md
Check it worked
current.mdholds the delivered text of v2, withsay what you left outin itsSHOULDline.instruction refs <id>showslatestandstableboth at v2.instruction get <id>showslatest: v2.
Clean up
Stop the watcher with Ctrl-C, then:
instruction delete <id> Move Support Agent to the trash?
It can be restored from the trash for 30 days, then it is deleted for good.
1 agent(s) follow it; they keep their last version but get nothing new.
Go ahead? [y/N] y
moved <you>/support-agent (<id>) to the trash; it is deleted for good after <date> The instruction stays in the trash for 30 days. instruction delete <id> --purge deletes it for good now; that asks first too.
If it doesn't work
The CLI prints tool: code: message for what the server refused, and exits with a code that says what kind of failure it was.
| What you see | Why | What to do |
|---|---|---|
support-agent.md exists (exit 2) |
init never overwrites a file. |
Pick another name, or delete the file. |
${environment} is required and has no value [parameter-missing] (exit 1) |
A required parameter has no value. | Pass it as environment=staging. |
… (this registry needs a signed-in caller: run `instruction login`, or pass --token) (exit 3) |
Not signed in, or the sign-in ran out and couldn't be refreshed. | Run instruction login again. |
connect https://instruction.md/mcp: … (exit 3) |
The server couldn't be reached, or it doesn't speak MCP 2026-07-28. | Check your network or proxy; --url or INSTRUCTION_MD_URL may point elsewhere. |
Who can read the first version of Support Agent? … then (say it with --visibility private, internal or public) (exit 2) |
The first release must say who reads it. | Add --visibility private. |
instructions_publish: this asks first; nothing changed (run again with --yes to go ahead) (exit 7) |
No terminal to ask on. | Run it again with --yes. |
cancelled; nothing changed (exit 7) |
You answered something other than y. |
Run it again and answer y. |
instructions_create: limit_reached: this plan keeps … private instructions; … (exit 1) |
Your plan's private instructions are all used. | Delete one, make one public, or upgrade. |
instructions_publish: conflict: nothing changed since the latest version (exit 1) |
The draft is the same as the latest version. | Change the file and push --to <id> first. |
… version_conflict: … (exit 1) |
The draft changed between your read and your write, for example in the editor. | Run the command again; it reads the current revision first. |
…: forbidden: … (exit 5) |
Your role doesn't allow it, such as a Contributor releasing. | Ask a Maintainer, or see Policy and roles. |
error: read: not_found: … from watch |
The ref doesn't exist, such as stable before step 7. |
Create it with instruction refs <id> set stable v1. |
Exit codes: 1 error, 2 usage or a refused input, 3 transport or not signed in, 4 not found, 5 forbidden, 6 nothing applied (watch --once), 7 not confirmed. The full list of messages is in Errors and Troubleshooting.
Next
- Connect an MCP client: give Claude, ChatGPT or your own client the same instruction.
- Claude Code: make a project follow
stablewithinstruction agents follow. - Publish and check from CI: validate, check and release on every merge.
- The model: drafts, versions, refs and followers, as the API names them.
- instruction command reference: every command and flag.