CLI: Job Instructions

opentrain instructions reads and edits the same pages shown in a real job’s employer Instructions tab. Every command requires a job ID. The CLI has no standalone workspace, manual, binding, review, or publication commands.

Install the latest CLI. Core job Instructions require 0.5.2 or later; hosted visual proof requires 0.23.0 or later:

npm install -g @opentrain-ai/cli@latest
opentrain --version

Inspect and read

opentrain instructions inspect --job <job-id> --json
opentrain instructions pages list --job <job-id> --json
opentrain instructions page get --job <job-id> --page <page-id> --json
opentrain instructions capabilities --json
opentrain instructions verify --job <job-id> --json

inspect and pages list return the same canonical tree. Responses include the exact employer URL, whether pages are inherited from a folder, and whether the job is locked to folder-managed instructions.

Preview without writing

opentrain instructions page preview --job <job-id> \
  --content-file ./page.tiptap.json --json

Preview validates, normalizes, and renders a complete TipTap doc node and returns writesApplied: false. Its checksum uses the same normalization as the live TipTap document.

Every mutation performs a complete no-write preflight when --confirm-live is absent. The server validates the target job, page, checksum, placement, rich document, and resulting tree. A confirmed retry obtains a short-lived signed token for that exact operation; changed input cannot reuse it.

Create and import

opentrain instructions page create --job <job-id> --title "Task workflow" \
  --content-file ./page.tiptap.json --key task-workflow-v1 \
  --after <page-id> \
  --confirm-live --json

opentrain instructions import docx --job <job-id> \
  --file ./project-guide.docx --title "Project guide" \
  --key project-guide-docx-v1 --confirm-live --json

Use --parent <root-page-id> for one subpage level. Place a new page with one of --before, --after, or --position. Deeper nesting is rejected to match the employer editor.

DOCX import converts supported headings, paragraphs, formatting, links, lists, and tables. Conversion uses deterministic node IDs and image identities, maps Word title styles, and preserves header versus body table cells. Preview plans the stable final image URLs without uploading bytes. Warnings block live import unless you explicitly allow their codes with --allow-warning.

Edit pages

opentrain instructions page patch --job <job-id> --page <page-id> \
  --expected-checksum <sha256> --ops-file ./patch.json \
  --confirm-live --json

opentrain instructions page replace --job <job-id> --page <page-id> \
  --expected-checksum <sha256> --content-file ./page.tiptap.json \
  --confirm-replace --confirm-live --json

opentrain instructions page rename --job <job-id> --page <page-id> \
  --title "New title" --json

opentrain instructions page rename --job <job-id> --page <page-id> \
  --title "New title" --confirm-live --json

opentrain instructions page move --job <job-id> --page <page-id> \
  --parent <root-page-id> --confirm-live --json

opentrain instructions page archive --job <job-id> --page <page-id> \
  --confirm-archive --confirm-live --json

Patch and replacement use the checksum from the last page read. A mismatch returns a conflict instead of overwriting another writer. Every applied command reads the canonical page or tree back before reporting success.

The server stages single-page content under a new TipTap document identity and atomically switches the job page after validation. This prevents an open collaboration session from merging a wholesale agent replacement into the old document.

The first rename command performs a signed no-write preflight. Add --confirm-live only after reviewing that result. page rename and page move return compact page metadata by default. Use page get when you need the complete document.

Run opentrain instructions page patch --help (or opentrain instructions page patch help) for examples of all six stable-ID operations: replace_node, insert_before, insert_after, append_children, set_attrs, and delete_node.

Use opentrain instructions page replace --help for the complete replacement flags and live-write boundary.

Work on a complete page tree

Use a local bundle when a change spans several pages:

opentrain instructions checkout --job <job-id> --dir ./instructions --json
opentrain instructions status --dir ./instructions --json
opentrain instructions diff --dir ./instructions --json
opentrain instructions validate --dir ./instructions --json
opentrain instructions plan --dir ./instructions --out ./instructions.plan.json --json
opentrain instructions apply --plan ./instructions.plan.json --confirm-live --json
opentrain instructions verify --job <job-id> --against-bundle ./instructions --json

The bundle is a non-authoritative working copy. plan fails when the live tree has drifted and records the exact desired tree and archive set. apply uses a fresh signed preflight and changes the complete tree atomically, so workers do not see a half-created hierarchy. Keep the generated journal with the plan for retry evidence. A content-only edit produces only its content action; unchanged pages are not repeated as no-op ordering actions. If the plan changes, regenerate it instead of editing its JSON.

Images

Plan an image upload without writing, then upload the exact reviewed bytes:

opentrain instructions image upload --job <job-id> \
  --file ./workflow.png --key workflow-image-v1 --json

opentrain instructions image upload --job <job-id> \
  --file ./workflow.png --key workflow-image-v1 \
  --expected-sha256 <sha256-from-preview> --confirm-live --json

The CLI detects JPEG, PNG, WebP, GIF, and AVIF from file bytes. The first run returns the deterministic final URL with writesApplied: false. The confirmed run refuses locally if the file’s SHA-256 no longer matches the preview, then verifies that the uploaded URL, content type, and byte size match the plan. Uploading does not edit a page; add the returned URL as an image node through a page or bundle mutation.

If you discover the removed instructions assets command in an old script, run opentrain instructions assets help. CLI 0.5.2 routes that help request to the canonical job-bound instructions image upload workflow. Detached Studio asset mutations remain unavailable.

instructions capabilities --json returns image.allowedHostPatterns, the hostname patterns the worker and employer renderer accepts. Upload an external image through this command before adding it when its host is not listed. DOCX import performs the same plan-and-upload sequence automatically. General file, audio, and video attachments are not currently supported by job Instructions.

Visual review

# Legacy, no-render checklist:
opentrain instructions visual-check --job <job-id> --json

# Agent-usable visual proof through the real OpenTrain renderer:
opentrain instructions visual capabilities --json
opentrain instructions visual session create \
  --job-id <job-id> --audience EMPLOYER --page-id <page-id> \
  --idempotency-key instructions-review-v1 --json
opentrain instructions visual render \
  --session-id <session-id> --expected-state-revision <revision> \
  --viewports desktop,mobile --out ./instructions-proof \
  --idempotency-key instructions-render-v1 --json

visual-check remains a fast checklist. The instructions visual family goes further: OpenTrain opens the actual employer Instructions workspace in real Chromium and returns desktop/mobile PNGs, an ARIA snapshot, diagnostics, and a provenance manifest. --out downloads the complete evidence set only after the CLI verifies every artifact’s checksum and byte size. Agents can inspect these files directly; they do not need a browser session or a Vercel account.

To verify the worker surface, create the session with --audience WORKER and a real designated test contract:

opentrain instructions visual session create \
  --job-id <job-id> --audience WORKER \
  --worker-contract-id <test-contract-id> --page-id <page-id> \
  --idempotency-key worker-review-v1 --json

The response reports typed workerCoverage; it never substitutes a synthetic worker. Each render also reports source drift between the pinned page tree and the live canonical Instructions. Visual proof deliberately leaves collaborationSyncVerified: false: a screenshot proves the captured render, not propagation to an already-open collaborative browser.

Use session select for incremental page or stable-node review. Create a short-lived human review link with links create; the reviewer signs in to OpenTrain normally. These links are OpenTrain-authenticated and never depend on Vercel deployment protection. See Hosted Instructions visual proof.

Safety boundary

Job instruction writes are immediately visible to hired AI trainers. There is no publish step. --confirm-live is the explicit boundary between preflight and write; it is not an approval workflow. The server accepts only the exact operation bound to its signed preflight token, then the CLI performs canonical readback before reporting success.

If an older command such as instructions workspaces, instructions manuals, or instructions publish is used, the CLI fails locally and points to these job-scoped commands.