Skip to content
OpenTrain AIOpenTrain AIOpenTrain AIDocs

Ask OpenTrain

Answers from the documentation, with sources.

What would you like to do with OpenTrain?

AI answers can be mistaken. Check the linked sources. Don’t include private account information.

Open app

DEVELOPER DOCUMENTATION

CLI: Job Instructions

Build, review, atomically apply, and verify the real Instructions pages attached to an OpenTrain job.

opentrain instructions reads and edits the same pages shown in a real job’s employer Instructions tab. Authoring selects a job with --job or a shared folder with --folder; do not supply both. 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, and its live-propagation probe requires 0.36.0 or later:

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

Shared folder authoring and migration require 0.27.0 or later. Follow Manage shared folder Instructions for zero-write inventory/preview, reviewed activation, copying existing job pages, cancellation and recovery. After activation, the authoring examples below also accept --folder <folder-id> in place of --job <job-id>. Execution defaults to one JSON envelope; --json remains a compatibility alias, while --pretty explicitly requests readable output.

Terminal window
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.

Terminal window
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.

Terminal window
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.

Terminal window
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.

Use a local bundle when a change spans several pages:

Terminal window
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.

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

Terminal window
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.

For supported instruction videos, use the page-bound upload workflow:

Terminal window
opentrain instructions video upload --job <job-id> --page <page-id> \
--file ./walkthrough.mp4 --duration-seconds 30 --key walkthrough-v1
opentrain instructions video status --job <job-id> --asset <asset-id>

Use the actual media duration. Upload reserves provider storage and transfers bytes; it is not a no-write preview. Inspect the result before inserting the video into your page. Storage-ready and playback-ready are different states; verify actual playback in the employer and AI trainer views. Use --folder for a folder page. Migration preserves supported existing audio/file/video references, but does not add a general-purpose file or audio upload command.

Terminal window
# 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:

Terminal window
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.

YouTube and Loom player frames load in the proof. Every other third-party embed is blocked by design and renders blank in the PNG while the render still succeeds; the diagnostics artifact lists the blocked address under blockedRequests. When the render measured the count, the result’s manifest.warnings also has a coded THIRD_PARTY_EMBED_BLOCKED string with the number of blocked embeds and no address. YouTube and Loom players are never in the count. The REST API can also return the count as a typed renderWarnings field; see Third-party embeds.

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.

CLI 0.36.0 or later can check whether a view that is already open shows a change that another writer commits. Create a fresh session with the page selected, then render it with --sync-timeout-ms:

Terminal window
opentrain instructions visual session create \
--job-id <job-id> --audience EMPLOYER --page-id <page-id> \
--idempotency-key sync-session-v1 --json
opentrain instructions visual render \
--session-id <session-id> --expected-state-revision <revision> \
--sync-timeout-ms 45000 \
--expected-page-checksum <page-checksum> \
--expected-tree-checksum <tree-checksum> \
--idempotency-key sync-probe-v1 --json

While the render runs, commit the page body and page-tree change from a separate process. The CLI waits up to 130 seconds for the result.

  • --sync-timeout-ms takes 5000 to 45000 milliseconds: how long the probe watches the open view. It works only for Instructions and only with the desktop viewport, so omit --viewports or pass --viewports desktop.
  • --expected-page-checksum and --expected-tree-checksum are optional, 64-character lowercase hex values from your writer’s receipt. They need --sync-timeout-ms.
  • Flag errors fail locally with exit code 2 before any request is sent.
  • A verified probe prints the render with livePropagationVerified: true and its syncReport. The CLI checks that response against the published schema first; if it does not match, the CLI prints no values.
  • A probe that is not verified exits with code 1. Its failure document has error.status 409, and error.details carries the reason, the syncReport, and the artifactIds. --out downloads nothing in that case; read the evidence with artifacts list --session-id <session-id>.
  • The session must have a page selected, or the render fails with SYNC_PAGE_REQUIRED. --page-id on render only asserts the selection; use session select to change it.
  • Each experiment needs a new session and a new idempotency key. Retrying the same key returns the saved result and never starts another observer.

livePropagationVerified: true proves that the change reached the scoped read-only view. collaborationSyncVerified stays false, so the probe proves nothing about live collaborative editors. See Live-propagation probe for every status and failure reason.

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.