Cette page n’est pas encore traduite.

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 with instruction 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

Shell
instruction export acme/support-agent@v3 --dir support-agent-v3
Output
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, as instructions_versions_get answers 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

Shell
instruction export acme/support-agent --format zip
Output
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:

acme-support-agent.zip
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, and exportedAt.
  • refs.json: every ref with the version it points at and its gates.
  • versions/vN.md and versions/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.

Shell
instruction export acme/support-agent --format oci --out support.tar
Output
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:

support.tar
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:

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

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

A zip, an OCI layout, an account or an audit export: asked for, made in the background, read in parts.
  1. 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, with fileName, version, digest, content and signatures. Its versionId takes ver_…, vN, a ref or draft (default: the default ref). draft answers the draft's text with draft.revision instead of version and signatures, if you may read the draft. A zip or an OCI layout takes no versionId: validation: a zip or an OCI layout holds every version; versionId is for md.

  2. Wait for it

    Read me://exports. It lists your exports still kept, newest first, each with its jobId, and your export jobs of the last day with their state (queued, running, done, failed). When an entry has your jobId, the file is ready. You are also told in me://inbox: "The export of Support Agent is ready", or "The OCI artifact of Support Agent is ready".

  3. 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, /1 and so on up to parts - 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 is digest.

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

Shell
instruction audit export --org acme --from 2026-10-01T00:00:00Z --format csv --out audit.csv
Output
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:

CSV header
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:

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

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

Last checked against the product:

Was this page helpful? Report a problem