لم تُترجم هذه الصفحة بعد.

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.

The quickstart, step by step, in a terminal.

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

  1. Install the CLI

    Shell
    npm i -g instruction.md
    instruction --version

    It prints its version and the edition of the language it reads:

    Output
    instruction.md 0.11.2 (instruction/1)

    The package is instruction.md; the command it installs is instruction. To run it once without installing, put npx instruction.md where this page writes instruction.

  2. Scaffold an instruction

    Shell
    instruction init support-agent --template agent
    Output
    created support-agent.md

    init takes a name (.md is added) and --template minimal (the default) or --template agent. It refuses to overwrite a file that exists. The agent template 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 of staging or production. MUST[confirm-irreversible] gives the rule an id that stays the same when you reword it. The MUST (if …) rule applies only when its condition holds. The ::person and :::output, :::context, :::glossary blocks are delivered under headings that name their kind. Rules and blocks lists every keyword and kind.

  3. Check it, and see what an agent receives

    Shell
    instruction validate support-agent.md
    instruction fmt support-agent.md --write
    Output
    ok       support-agent.md

    validate reports what a release would refuse. Errors exit 1 and print INVALID; warnings print WARNED and pass unless you add --strict. --json prints each file's diagnostics and its authored digest. fmt prints the formatted text; with --write it rewrites the file and says formatted <file> only when something changed.

    Now ask for the delivered text without the required parameter:

    Shell
    instruction deliver support-agent.md
    echo $?
    Output
    line 1: ${environment} is required and has no value  [parameter-missing]
    1

    deliver prints nothing on stdout and exits 1 when a required parameter has no value. Give it as name=value:

    Shell
    instruction deliver support-agent.md environment=staging
    Output
    # 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=prod
    line 1: the value given for ${environment} is not a valid enum (staging, production)  [parameter-invalid]

    --resolved prints the resolved form as JSON instead. What an agent receives defines both.

  4. Sign in

    Shell
    instruction login
    
    # on a machine without a browser (SSH, a container): a code you enter on another device
    instruction login --device

    instruction login opens your browser. --device shows a code to enter on another device instead. When it finishes:

    Output
    Signed 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, under XDG_CONFIG_HOME when set) and refreshed as it runs out. instruction agents login uses the same sign-in. For CI, use a token instead: Agent credentials.

  5. Push the draft

    Shell
    instruction push support-agent.md --visibility private
    Output
    draft saved: <you>/support-agent revision 1
    instruction://<id>

    push without --to creates 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/name works too.

  6. Release the first version

    Shell
    instruction 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 for y:

    Output
    Release 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 terminal
    instruction publish <id> --message "First version" --visibility private --yes
  7. Create the stable ref

    stable is never created for you. Point it at v1:

    Shell
    instruction refs <id> set stable v1
    instruction refs <id>
    Output
    stable → v1 (ver_<v1>)
    latest       → v1    ver_<v1>  <time>
    stable       → v1    ver_<v1>  <time>

    latest moves on every release that doesn't name other refs (--refs, --quiet). stable moves 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 from latest: see Refs.

  8. Follow stable as an agent does

    In a second terminal, in an empty folder:

    Shell
    instruction watch instruction://<id>@stable --out current.md
    Output
    <time> applied v1 ver_<v1> (stable) → current.md
    watching instruction://<id>@stable (freshness 60s, follow); Ctrl-C to stop

    watch reads the version stable points at, writes its delivered text to current.md whole 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, watch prints live updates are taken: … Still reading on schedule. and keeps reading every 60 seconds. Live updates explains the limit.

  9. Release v2 and move stable

    In support-agent.md, change the SHOULD line to:

    support-agent.md
    SHOULD: prefer the smallest change that solves the problem, and say what you left out.

    Then, in the first terminal:

    Shell
    instruction push support-agent.md --to <id>
    instruction publish <id> --message "Say what was left out"
    instruction refs <id> set stable v2
    Output
    draft 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 moves latest, and nobody follows latest, so the follower count is 0. The watcher keeps v1 until stable moves. After refs … set stable v2, the watcher prints:

    Output, second terminal
    <time> applied v2 ver_<v2> (stable) ← ver_<v1> → current.md

Check it worked

  • current.md holds the delivered text of v2, with say what you left out in its SHOULD line.
  • instruction refs <id> shows latest and stable both at v2.
  • instruction get <id> shows latest: v2.

Clean up

Stop the watcher with Ctrl-C, then:

Shell
instruction delete <id>
Output
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

Last checked against the product:

Was this page helpful? Report a problem