Export and back up
For developers and operators who keep their own copy of what is on instruction.md: one version as a file, every version with its records, an OCI artifact for a container registry, your whole account, or the audit trail. Each export is a file you own. None of them changes the instruction.
| What | Command | Tool | File |
|---|---|---|---|
| One version | instruction export <uri> [--dir D] |
instructions_export, format: md |
instruction.md and version.json |
| Every version | instruction export <id> --format zip |
instructions_export, format: zip |
<owner>-<name>.zip |
| An OCI image layout | instruction export <id> --format oci |
instructions_export, format: oci |
<owner>-<name>-oci.tar |
| Your account | none (MCP or the editor) | me_export |
instruction-md-export-<date>.zip |
| The audit trail | instruction audit export … |
instructions_audit_export |
audit-<scope>-<date>.ndjson or .csv |
Before you start
- The CLI, 0.11.0 or later (
npm i -g instruction.md), signed in withinstruction login, or a token in CI (Agent credentials). - To export an instruction, the right to read it. The zip includes the draft only if you may read the draft too.
- To export the audit trail: the Admin role on the instruction, or owner or admin of the organization, and a sign-in made with
instruction login --admin. See Audit trail. - To export your account: a person's own sign-in. An agent credential can't ask for it.
Export one version
instruction export acme/support-agent@v3 --dir support-agent-v3 exported v3 (ver_<id>) → <cwd>/support-agent-v3/{instruction.md, version.json} <uri> is an address that reads a version: acme/support-agent (its default ref), acme/support-agent@stable, @v3, @ver_…, or the same with instruction:// in front. The draft isn't a version, so …/draft is refused: <uri>: not a version (export reads one, e.g. instruction://<id>@latest). To read a draft, use instruction pull <id>/draft --out FILE.
The folder (--dir, default the current one) gets two files:
instruction.md: the version's authored text, byte for byte.version.json: its record, asinstructions_versions_getanswers it: number, message, author, refs, digest, signatures and checks. Signing and verification says how to check the signature against the digest.
Both files are overwritten if they exist.
Export every version
instruction export acme/support-agent --format zip acme-support-agent.zip → <cwd>/acme-support-agent.zip The server makes the file in the background. The CLI waits for it, up to 3 minutes, then writes it to --out FILE, or into --dir under its own name. The zip holds one folder, named after the instruction:
support-agent/
instruction.json
refs.json
draft.md
versions/
v1.md
v1.json
v2.md
v2.json
v3.md
v3.json instruction.json: id, address, owner, name, title, description, visibility, kind, tags, default ref, latest version, origin, source path, dates, andexportedAt.refs.json: every ref with the version it points at and its gates.versions/vN.mdandversions/vN.json: each version's text and its record. Revoked versions are included, with their record saying so.draft.md: the draft's accepted text, only when you may read the draft.
An instruction with no version yet exports as a zip of its draft, if you may read the draft.
Export an OCI image layout
An OCI export lets you keep instructions in the container registry you already run, next to the images that use them.
instruction export acme/support-agent --format oci --out support.tar acme-support-agent-oci.tar → <cwd>/support.tar
push it: mkdir layout && tar -xf support.tar -C layout && oras cp --from-oci-layout layout:latest REGISTRY/REPO:latest The tar is an OCI image layout:
oci-layout
index.json
blobs/
sha256/
<manifest, config and layer of each version> Each version is one manifest, tagged vN, and also tagged with the name of every ref that points at it, such as latest or stable. Each manifest has:
| Part | Media type | Holds |
|---|---|---|
| Artifact type | application/vnd.instruction-md.instruction.v1 |
|
| Config | application/vnd.instruction-md.version.v1+json |
The version's record, with its canonical address |
| Layer | application/vnd.instruction-md.instruction.v1+markdown |
The authored text, titled <name>.md |
Its annotations are org.opencontainers.image.title, .version (vN), .revision (the version id), .created and .description (the release message), and md.instruction/canonical, md.instruction/spec, md.instruction/digest, md.instruction/publisher and md.instruction/signature. An annotation with no value is left out.
Push it to a registry with ORAS. Unpack the tar first, then copy the tags you want:
mkdir layout && tar -xf support.tar -C layout
oras cp --from-oci-layout layout:v3 registry.example.com/acme/support:v3
oras cp --from-oci-layout layout:stable registry.example.com/acme/support:stable Anyone who can pull from that registry gets the text back under its own name:
oras pull registry.example.com/acme/support:v3
# writes support-agent.md, the layer's title An instruction with no version can't be exported this way: conflict: nothing is released yet: an OCI artifact holds versions. The stable tag exists only if you made a stable ref; see A stable version.
Export over MCP
The zip and the OCI layout are background jobs. A client asks for one, waits for it on me://exports, then reads it in parts.
Ask for the export
tools/call{ "name": "instructions_export", "arguments": { "instructionId": "acme/support-agent", "format": "zip", "idempotencyKey": "<uuid>" } }The answer comes at once, with the job:
Result{ "instructionId": "ins_<id>", "format": "zip", "jobId": "job_<id>", "kind": "instruction.export", "state": "queued", "links": ["me://exports"] }Asking again while that job is on its way answers the same job. With an
idempotencyKey, the same call sent again after the file was made answers that one too.format: md(the default) makes no job: it answers the text at once, withfileName,version,digest,contentandsignatures. ItsversionIdtakesver_…,vN, a ref ordraft(default: the default ref).draftanswers the draft's text withdraft.revisioninstead ofversionandsignatures, if you may read the draft. A zip or an OCI layout takes noversionId:validation: a zip or an OCI layout holds every version; versionId is for md.Wait for it
Read
me://exports. It lists your exports still kept, newest first, each with itsjobId, and your export jobs of the last day with their state (queued,running,done,failed). When an entry has yourjobId, the file is ready. You are also told inme://inbox: "The export of Support Agent is ready", or "The OCI artifact of Support Agent is ready".Read it
Read
me://exports/{id}:me://exports/exp_…{ "id": "exp_<id>", "fileName": "acme-support-agent.zip", "mediaType": "application/zip", "size": 18342, "digest": "sha256:<digest>", "parts": 1, "partSize": 150000, "createdAt": "<ISO 8601>", "expiresAt": "<ISO 8601, 7 days later>", "links": ["me://exports/exp_<id>/0"] }Then read
me://exports/{id}/0,/1and so on up toparts - 1. Each part is a base64 blob of at most 150,000 bytes. Decode them in order and join them. The SHA-256 of the result isdigest.
An export is kept for 7 days, and only the person or agent who asked can read it. Resources and their addresses are listed on Resources and addresses, and the tools on Tool reference.
Export your account
me_export makes one zip of everything you own. It takes only an optional idempotencyKey, answers a jobId at once, and works the same way as the steps above. You are told "Your export is ready". There is no CLI command for it. In the editor it is Your account ▸ Privacy ▸ Download your data; see Your data.
The zip holds, for every instruction of every organization where you are owner or admin, your personal one included:
<owner>/<name>/draft.md: the draft.<owner>/<name>/vN.md: each version's text.
And account.json: your profile and your preferences. Version records, refs and comments aren't in it; export an instruction as a zip for those.
Export the audit trail
instruction audit export --org acme --from 2026-10-01T00:00:00Z --format csv --out audit.csv audit-org_<id>-<YYYY-MM-DD>.csv → audit.csv The scope is one instruction (<id|uri>) or a whole organization (--org). The filters are --types a,b, --from and --to (ISO 8601). --format is ndjson (the default, one record per line, whole) or csv, with these columns:
at,type,source,actor_kind,actor_id,actor_name,client,instruction_id,version_id,transport,outcome,summary Without --out, the file goes to standard output. --self filters instruction audit (the last 100 records) only; with export it is refused, exit 2. Over MCP, instructions_audit_export also takes except, q, workspaceId, principal, transport and outcome. A CSV cell that starts with =, +, -, @, a tab or a carriage return gets a ' in front, so a spreadsheet doesn't run it as a formula.
The audit trail records who did what and who read what. It never holds an instruction's content. What is recorded, and for how long, is on Audit trail.
Restore from an export
An export is plain text, so restoring it is a push. Put an exported version back as the draft of the same instruction, then release it:
instruction push support-agent/versions/v3.md --to acme/support-agent
instruction publish acme/support-agent --message "Restored from the v3 export" The release asks first, because it moves the default ref. Add --yes without a terminal. If the old instruction is gone, push the text as a new one and release its first version, which needs --visibility:
instruction push support-agent/versions/v3.md --org acme --name support-agent
instruction publish <id> --visibility private --message "Restored from an export" A restored text becomes a new version, with the next number, a new id and a new signature. The old version's number, record and refs aren't restored; keep version.json and refs.json as the record of what was. When the version still exists on the server, you don't need the file: instructions_restore puts a version's text back into the draft. Every command is on instruction command reference.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
--format is zip or oci (a single version: leave it out) |
Another value for --format |
Use zip or oci, or no --format for one version. |
<uri>: not a version (export reads one, e.g. …@latest) |
The address reads the draft, or nothing is released | Name a version or a ref, or use instruction pull <id>/draft. |
the export (job_…) is taking a while; your notifications will say when it's ready (me://exports) |
The job took more than 3 minutes | Wait for the notice, then read it from me://exports within 7 days. |
| A notice: "Your export wasn't made: it would hold … MB, and an export holds at most 64 MB." | The texts add up to more than 64 MB | Export fewer instructions at a time. An account export can't be split; export its instructions one by one. |
instructions_export: conflict: nothing is released yet: an OCI artifact holds versions |
The instruction has no version | Release one, or export a zip. |
`instruction audit export` administers an organization… and exit 3 |
Your sign-in lacks the admin permission (without a terminal; in one, the CLI offers to sign you in again) | Run instruction login --admin once, then run it again. |
| Still stuck | Ask on Support. |
Questions
How do I export every version (zip or OCI)?
Run instruction export <id> --format zip for a zip with every version's text and record, or --format oci for an OCI image layout tagged vN and with the refs' names. See Export every version.
How long is an export kept?
7 days, on me://exports, readable only by whoever asked for it. The CLI downloads it as soon as it is made. See Export over MCP.
Does the audit export include the text of my instructions?
No. It records events and reads, never content. Export the instruction itself for its text. See Export the audit trail.
Does an export keep the signatures?
Yes. Each version's record carries its signatures, in version.json, in versions/vN.json and in the OCI annotations. A restored text is signed again as a new version. See Restore from an export.