CLI: Instructions

opentrain instructions is the agent-first authoring surface for instruction manuals. Every command wraps the corresponding Instructions API endpoint, supports --json for the raw response, and accepts - for stdin on file inputs. --key <idempotency-key> is available on workspace/manual creation, direct and stored changeset apply, changeset submit, revision restore, publish, and docs-as-code sync—not on update, archive, permission, reviewer-decision, or asset commands. Requires CLI 0.3.0 or later (npm install -g @opentrain-ai/cli@latest). Changeset-backed page authoring helpers and sync accept --dry-run to validate without writing and --submit to store the changeset for human review. Those flags do not apply to metadata, permission, reviewer-decision, asset, or publication commands. Whole-document replacement always demands the explicit --confirm-replace flag.

Discovery and search

opentrain instructions capabilities --json
opentrain instructions search --query "bounding boxes" [--workspace <id>] [--manual <id>] [--audience WORKER]

Workspaces and permissions

opentrain instructions workspaces list|get|create|update|archive
opentrain instructions workspaces create --name "Operations" [--key <k>]
opentrain instructions permissions list --workspace <id>
opentrain instructions permissions grant --workspace <id> --principal <userId> --role EDITOR|REVIEWER|VIEWER
opentrain instructions permissions revoke --workspace <id> --principal <userId>

Workspace creation also requires a verified user with employer organization membership and persists the creator’s OWNER permission record. Permission listing needs both instructions:read and instructions:publish; list/grant/revoke require workspace OWNER. Granting an existing principal updates their role.

Manuals and trees

opentrain instructions manuals list --workspace <id>
opentrain instructions manuals create --workspace <id> --title "Reviewer handbook" \
  [--audience REVIEWER] [--binding JOB:<jobId>[:precedence]]... [--key <k>]
opentrain instructions manuals get|update|archive --manual <id>
opentrain instructions tree --manual <id> [--audience WORKER] [--include-archived]

Archive commands require workspace OWNER. They retain rows but make the archived workspace/manual inaccessible through the current public API. tree --audience is an exact-match draft filter.

Pages

opentrain instructions page get --page <id> [--revision N] [--format json|html|markdown]
opentrain instructions page create --workspace <id> --manual <id> --title "Edge cases" \
  [--parent <pageId>] [--content-file doc.json|-] [--page-key <clientPageKey>]
opentrain instructions page patch --workspace <id> --page <id> --base-revision N \
  [--base-checksum <sha256>] --ops-file patch.json|-
opentrain instructions page replace --workspace <id> --page <id> --base-revision N \
  --content-file doc.json --confirm-replace
opentrain instructions page move --workspace <id> --page <id> (--parent <id> | --root) [--position N]
opentrain instructions page rename|archive|restore --workspace <id> --page <id> [...]

--format markdown always prints the machine-readable loss report alongside the render — nothing is silently down-converted. Content files accept a full canonical envelope or a bare doc node (the CLI wraps and checksums it locally).

Changesets

opentrain instructions changeset validate|diff|apply|submit --file changeset.json|- [--workspace <id>]
opentrain instructions changeset list --workspace <id> [--status SUBMITTED]
opentrain instructions changeset get --changeset <id>
# Reviewer lifecycle
opentrain instructions changeset approve --changeset <id> [--note "…"]
opentrain instructions changeset reject  --changeset <id> [--note "…"]
opentrain instructions changeset apply   --changeset <id> [--key <k>]   # apply a stored APPROVED proposal

A CREATE_PAGE operation with clientPageKey: "x" can be referenced by other operations in the same file as parentPageId: "new:x", in any order. Conflicted applies print structured conflicts and exit non-zero.

Versions and publications

opentrain instructions versions list --manual <id>
opentrain instructions versions diff --manual <id> --a N --b N
opentrain instructions versions restore --manual <id> --revision N [--key <k>]
opentrain instructions publications list --manual <id>
opentrain instructions publish --manual <id> --base-revision N [--audience WORKER]... [--note "…"] [--key <k>]
opentrain instructions manifest --manual <id> --publication N [--audience WORKER]

Restore never rewrites history — it lands as a new revision. Publishing needs instructions:publish plus workspace OWNER. Omitting every --audience publishes to all four audiences; pass one or more flags for a narrower release.

Private media

opentrain instructions assets upload --workspace <id> --file ./walkthrough.mp4   # prepare + PUT + finalize
opentrain instructions assets prepare|finalize|list|get [...]
opentrain instructions assets attach --workspace <id> --page <id> --asset <id> [--node <nodeId>]

The CLI hashes the file locally (SHA-256), infers the kind from the MIME type, and attaches by asset ID — documents never carry raw storage URLs. Finalization confirms trusted upload metadata but does not independently re-hash the stored bytes server-side.

Docs-as-code: checkout, status, diff, sync

opentrain instructions checkout --workspace <id> --manual <id> --dir ./handbook
opentrain instructions status --dir ./handbook [--remote]
opentrain instructions diff --dir ./handbook
opentrain instructions sync --dir ./handbook --confirm-replace [--dry-run] [--submit] [--key <k>]

checkout writes each page as canonical JSON plus a manifest of page IDs, revisions, and checksums. Edit the files, inspect drift with status/diff, then sync pushes every modified page back as one revision-guarded changeset and advances the manifest. --dry-run validates first; --submit routes the sync through human review.

Render previews

opentrain instructions preview --page <id> [--revision N] --format html|markdown
opentrain instructions preview --content-file doc.json --format markdown

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Discovery and search

Workspaces and permissions

Manuals and trees

Pages

Changesets

Versions and publications

Private media

Docs-as-code: checkout, status, diff, sync

Render previews

​Discovery and search

​Workspaces and permissions

​Manuals and trees

​Pages

​Changesets

​Versions and publications

​Private media

​Docs-as-code: checkout, status, diff, sync

​Render previews

Discovery and search

Workspaces and permissions

Manuals and trees

Pages

Changesets

Versions and publications

Private media

Docs-as-code: checkout, status, diff, sync

Render previews