CLI: Project To-dos and Quizzes

opentrain todos manages the same Project To-dos list employers and AI trainers see in the product. Every fan-out command previews by default and writes only with explicit confirmation.

The complete Project To-dos and selective-coaching command tree requires CLI 0.14.0 or later. Hosted Native Forms visual proof requires 0.23.0 or later:

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

The configured account must have the Project To-dos agent surface enabled. A full-access key supplies project_todos:read and project_todos:write, but it does not bypass that account gate; AGENT_SURFACE_DISABLED means the account needs enablement, not another token rotation.

Read and report

opentrain todos list --job-id <job-id> --json
opentrain todos list --job-id <job-id> --needs-review --json
opentrain todos list --job-id <job-id> --assigned-to <contract-id> --include-archived --json
opentrain todos export-csv --job-id <job-id>
opentrain todos schema            # action schemas for the manage union
opentrain todos help

List output includes the flat item catalog, per-person progress, and a pre-pagination summary. Personal emails never appear; people are shown as contract IDs with masked names.

Create and assign (preview first)

Running without --confirm-live is a no-write preview: it prints the exact masked recipients and count, future-hire semantics, projected due/blocking behavior, duplicate candidates, warnings — and, for broad audiences, the preflight receipt token with its expiry.

# Personalized, exact recipients — no receipt needed:
opentrain todos create-item --job-id <job-id> --audience SELECTED \
  --contract-id <contract-id> --version-file ./todo.json          # preview
opentrain todos create-item --job-id <job-id> --audience SELECTED \
  --contract-id <contract-id> --version-file ./todo.json \
  --confirm-live --idempotency-key onboarding-sop-v1              # live

# Broad audience — two explicit steps:
opentrain todos create-item --job-id <job-id> --audience ACTIVE_AND_FUTURE \
  --version-file ./todo.json --json                               # preview prints receipt
opentrain todos create-item --job-id <job-id> --audience ACTIVE_AND_FUTURE \
  --version-file ./todo.json --confirm-live --yes \
  --preflight-receipt <token-from-the-preview> \
  --idempotency-key guidelines-refresh-v2                         # live

• --audience is always required; there is no default.
• SELECTED takes repeatable --contract-id flags or --contract-ids a,b; duplicate or non-SELECTED stray IDs are rejected before any network call.
• Broad live runs require --yes and --preflight-receipt from the preview you reviewed, so a roster or payload change since that preview fails server-side instead of assigning people you never saw.
• --allow-duplicate overrides the exact-duplicate refusal.
• todos assign-item and todos archive-item follow the same preview-then-confirm shape; the archive preview prints exactly how many open assignments will close.

Review and transitions

opentrain todos review --assignment-id <id> --decision APPROVE --idempotency-key r1
opentrain todos review --assignment-id <id> --decision RETURN --reason "Fix step 2" \
  --expected-submitted-at 2026-08-27T04:10:00.000Z --idempotency-key r2
opentrain todos transition --assignment-id <id> --transition COMPLETE --idempotency-key t1

These single-assignment commands execute directly — no --confirm-live step. Pass a stable --idempotency-key so retries converge (one is generated when omitted). --expected-submitted-at is the stale-review guard: a resubmission in the meantime rejects the decision.

Enable, disable, and the raw escape hatch

opentrain todos enable --job-id <job-id>
opentrain todos disable --job-id <job-id>
opentrain todos manage --body-file ./action.json   # advanced/raw

todos manage cannot bypass safety: create_item, assign, and archive_item bodies are redirected to the focused commands, and fan-out actions without an explicit audience fail before any request is sent.

Quizzes

opentrain todos quiz list --job-id <job-id> --json
opentrain todos quiz create --job-id <job-id> --title "Safety check" --kind QUIZ --confirm-live
opentrain todos quiz update --form-id <id> --definition-file ./quiz.json --expected-revision 3 --confirm-live
opentrain todos quiz publish --form-id <id> --expected-draft-revision 4 --confirm-live

# Assigning previews by default, like create-item:
opentrain todos quiz assign --job-id <job-id> --form-version-id <id> \
  --audience SELECTED --contract-id <contract-id>                 # preview
opentrain todos quiz assign --job-id <job-id> --form-version-id <id> \
  --audience SELECTED --contract-id <contract-id> \
  --confirm-live --idempotency-key safety-quiz-v1                 # live

opentrain todos quiz attempts --job-id <job-id> --form-id <id> --json
opentrain todos quiz attempt --attempt-id <id> --json
opentrain todos quiz roster --job-id <job-id> --form-id <id> --json
opentrain todos quiz export-results --job-id <job-id> --form-id <id>
opentrain todos quiz grade --attempt-id <id> --grades-json '[{"questionId":"q1","awardedPoints":5}]' --confirm-live
opentrain todos quiz release --attempt-id <id> --confirm-live
opentrain todos quiz bulk-release --job-id <job-id> --form-id <id> --confirm-live
opentrain todos quiz require-retake --assignment-id <id> --reason "Redo part II" \
  --expected-submitted-at <iso> --confirm-live --idempotency-key retake-1
opentrain todos quiz remediate plan --job-id <job-id> --rows-file ./rows.json   # no writes
opentrain todos quiz remediate apply --job-id <job-id> --rows-file ./rows.json \
  --plan-checksum <checksum-from-plan> --idempotency-key retake-batch-1 --confirm-live

Quiz assignment requires an explicit stable --idempotency-key so a retry cannot create duplicate worker-visible obligations; broad quiz audiences require --yes plus --preflight-receipt from the reviewed preview. remediate plan validates the whole full-retake batch without writing. remediate apply executes exactly those planned rows, bound to --plan-checksum, and rejects live drift with 409 PLAN_STALE.

Visually verify a quiz without creating an attempt

opentrain todos quiz preview capabilities --json
opentrain todos quiz preview session create \
  --form-id <form-id> --draft-revision <revision> \
  --question-id <question-id> \
  --idempotency-key quiz-preview-v1 --json
opentrain todos quiz preview render \
  --session-id <session-id> --expected-state-revision <revision> \
  --viewports desktop,mobile --out ./quiz-proof \
  --idempotency-key quiz-render-v1 --json

For a published quiz, replace --draft-revision with --form-version-id. OpenTrain renders the real worker Native Forms runner in Chromium and returns PNG, ARIA, diagnostics, and provenance evidence. The CLI checksum-verifies the complete evidence set before publishing it under --out, so an agent can inspect the screenshots without a browser login.

Preview is strictly isolated: it creates no attempt, answer, grade, result release, Project To-do transition, notification, or completion record. The worker-safe projection never contains answer keys. You can select another question with session select, or mint a short-lived observe-only link for a signed-in employer with links create. See Hosted quiz visual proof.

Selective coaching

Selective coaching returns only chosen questions with threaded feedback. It is separate from a full-quiz retake.

# Contract discovery works before the account feature is enabled:
opentrain todos quiz coaching capabilities

# Employer reads and a bounded masked export:
opentrain todos quiz coaching queue --job-id <job-id> --all
opentrain todos quiz coaching state --assignment-id <assignment-id>
opentrain todos quiz coaching export --job-id <job-id> --kind assignments --format jsonl --out coaching.jsonl

# Draft feedback, choose redo questions, then review a no-write plan:
opentrain todos quiz coaching comment --assignment-id <assignment-id> \
  --question-id <question-id> --attempt-id <attempt-id> --body-file ./feedback.json \
  --idempotency-key review-comment-1 --confirm-live
opentrain todos quiz coaching redo-selection --assignment-id <assignment-id> \
  --question-id <question-id> --idempotency-key review-selection-1 --confirm-live
opentrain todos quiz coaching send-back --assignment-id <assignment-id> \
  --review-cycle-id <review-cycle-id> --reason "Revise the selected questions" \
  --expected-submitted-at <iso-timestamp>                              # no writes

# Apply only the signed plan you reviewed:
opentrain todos quiz coaching send-back --assignment-id <assignment-id> \
  --review-cycle-id <review-cycle-id> --reason "Revise the selected questions" \
  --expected-submitted-at <iso-timestamp> \
  --plan-token <token-from-plan> --idempotency-key send-back-1 --confirm-live

Every coaching mutation requires both --confirm-live and a caller-supplied stable --idempotency-key; the CLI never invents one for this family. Use coaching image upload for the safe one-shot feedback-image workflow, or image prepare|finalize|status|download for lower-level transfer control. Signed storage grants are never printed.

Worker self-service commands use a worker-minted key and only the token owner’s assignment:

opentrain todos quiz respond context --assignment-id <assignment-id>
opentrain todos quiz respond start --assignment-id <assignment-id> \
  --idempotency-key worker-start-1 --confirm-live
opentrain todos quiz respond autosave --assignment-id <assignment-id> \
  --attempt-id <attempt-id> --answers-file ./answers.json --expected-revision <revision> \
  --idempotency-key worker-save-1 --confirm-live
opentrain todos quiz respond resubmit --assignment-id <assignment-id> \
  --attempt-id <attempt-id> --answers-file ./answers.json \
  --idempotency-key worker-submit-1 --confirm-live

These commands require project_todos:respond. Employer keys — including Full access — cannot call them, and worker output never includes answer keys, scoring rules, other workers, or private employer drafts.

See the selective-coaching API reference for every lane and the concept page for the safety model.