DEVELOPER DOCUMENTATION

CLI: Reviewer Feedback and Task Checklists

Use the CLI to review private feedback, manage reviewer access, author adaptive checklists, preview revisions, publish, and inspect submissions.

OpenTrain CLI 0.14.0 includes two job-quality command families:

opentrain feedback manages employer-private reviewer reports and reviewer grants.
opentrain checklists provides a file-first workflow for adaptive checklist authoring, visual review, publishing, and submission inspection.

npm install -g @opentrain-ai/cli@latest
opentrain capabilities
opentrain feedback help
opentrain checklists help

Output and idempotency

Both families print exactly one machine envelope by default:

{ "ok": true, "data": { "...": "..." } }

--json restates the default and is a compatibility no-op. Pass --pretty alone for a human summary plus indented JSON; combining the two modes is a usage error.

Every Reviewer Feedback mutation requires an explicit --key with 8–128 safe characters. Checklist push and publish can derive revision-bound keys; reversible settings, reorder, archive, and restore commands require an explicit key.

Review feedback across a job

Begin with the feature state, summary, and first report page:

opentrain feedback settings --job-id <job-id>
opentrain feedback summary --job-id <job-id>
opentrain feedback list --job-id <job-id> --status ALL --page 1

Filter by status, subject, severity, reporter, report text, and time range:

opentrain feedback list --job-id <job-id> \
  --status OPEN \
  --severity MAJOR \
  --search 'acceptance rule' \
  --created-from 2026-08-01T00:00:00Z \
  --created-to 2026-08-31T23:59:59Z

The list response has a fixed server page size and a hasMore flag. Continue with --page 2, --page 3, and so on until hasMore is false. Status counts are authoritative for the subject-filtered set; use feedback summary for job-wide totals, unresolved counts, per-person aggregates, and unlinked legacy rows.

Read one report before triaging it:

opentrain feedback get --report-id <report-id>

opentrain feedback triage \
  --report-id <report-id> \
  --to-status IN_REVIEW \
  --expected-updated-at <updatedAtIso-from-get> \
  --key feedback-review-482-v1

Use the exact updatedAtIso returned by the latest get. Terminal transitions and reopening require --note; a stale value returns 409 and requires another read and decision.

Discover subjects and submit employer feedback

The roster removes the need for a browser or database lookup:

opentrain feedback roster --job-id <job-id>

It returns each canonical person once with all contracts they held. Submit the report body inline or from a file:

opentrain feedback submit \
  --job-id <job-id> \
  --subject-user-id <user-id> \
  "--trainer-id" masked-482 \
  --task-id task-482 \
  --severity MAJOR \
  --suggested-action RETRAINING \
  --report-file ./feedback-task-482.txt \
  --key feedback-task-482-v1

The canonical subject is required for an employer-authored report. --subject-contract-id is optional; when omitted, OpenTrain stores a deterministic contract reference. Use feedback link-subject only to reconcile a legacy unlinked row:

opentrain feedback link-subject \
  --report-id <report-id> \
  --subject-user-id <user-id> \
  --note 'Matched against the project roster' \
  --key feedback-link-482-v1

Manage reviewer access and the job switch

Reviewer grants are available only for people with active contracts on the job:

opentrain feedback access list --job-id <job-id>

opentrain feedback access grant \
  --job-id <job-id> --user-id <user-id> --key feedback-grant-user-1-v1

opentrain feedback access revoke \
  --job-id <job-id> --user-id <user-id> --key feedback-revoke-user-1-v1

Bulk access changes are transactional. One ineligible grant target rejects the complete batch:

opentrain feedback access bulk \
  --job-id <job-id> \
  --user-ids <user-1>,<user-2>,<user-3> \
  --grant \
  --key feedback-grant-qc-team-v1

The per-job feature defaults off. Both directions require an acknowledgement and a durable key:

opentrain feedback enable \
  --job-id <job-id> --confirm --key feedback-enable-v1

opentrain feedback disable \
  --job-id <job-id> --confirm --key feedback-disable-v1

Disabling preserves reports, events, subject links, and grants.

Author a checklist from files

Create a local bundle directory and edit checklist.json:

opentrain checklists init \
  --dir ./image-qc \
  --title 'Image QC' \
  --required

The bundle contains a complete schemaVersion: 2 definition with title, required, and tree. Node IDs and option IDs are stable, caller-minted tokens. Use the API reference example for branching and repeat-group shapes.

Validate before writing, then push the new definition atomically:

opentrain checklists validate --dir ./image-qc
opentrain checklists push --dir ./image-qc --job-id <job-id>

push creates a complete definition when no base snapshot exists. For an existing definition, check it out first:

opentrain checklists checkout \
  --definition-id <definition-id> \
  --dir ./image-qc

opentrain checklists diff --dir ./image-qc
opentrain checklists validate --dir ./image-qc
opentrain checklists push --dir ./image-qc

The CLI keeps a private base snapshot and performs a three-way comparison across base, local bundle, and live remote draft. A conflicting edit fails closed instead of overwriting another employer’s work.

Resolve answers and visually review

Test branching, numeric constraints, required paths, and repeated blocks without storing answers:

opentrain checklists resolve \
  --definition-id <definition-id> \
  --source draft \
  --answers-file ./sample-answers.json

Preview the exact synchronized revision in a browser:

opentrain checklists preview --dir ./image-qc --source draft --open

Without --open, the response returns the short-lived previewUrl. The command refuses to preview a dirty local bundle—run push first so the rendered server snapshot is exactly the content you reviewed locally.

Publish, order, and enable

Publish after validation and browser review:

opentrain checklists publish --dir ./image-qc --confirm-live

The response identifies the immutable version and content hash, change impact, open runs swept, and answers that workers must reconfirm. Multiple definitions can be published for one job. List and reorder the complete set with a compare-and-set precondition:

opentrain checklists list --job-id <job-id>

opentrain checklists reorder \
  --job-id <job-id> \
  --expected <current-id-1>,<current-id-2> \
  --order <new-id-2>,<new-id-1> \
  --key checklist-reorder-v1

Enable the job only when every worker-visible definition is ready:

opentrain checklists enable --job-id <job-id> --key checklist-enable-v1

Disable requires --confirm; definitions, versions, and submissions remain stored:

opentrain checklists disable \
  --job-id <job-id> --confirm --key checklist-disable-v1

Review checklist results

Filter submission rows across the job and fetch the complete version-pinned result:

opentrain checklists submissions \
  --job-id <job-id> \
  --definition-id <definition-id> \
  --task task-482 \
  --page 1

opentrain checklists submissions --submission-id <submission-id>

The detail includes the exact submitted version’s title and tree, active answers, and inactive-path audit metadata. It never exposes raw hidden or orphaned answer values.