CLI Overview

The OpenTrain CLI (@opentrain-ai/cli, binary opentrain) wraps the Public API and the agent auth endpoints in a command-line surface built for both humans and coding agents. Legacy command families print a human-readable summary by default and exact API JSON with --json. New agent-first families—including adaptive Task Checklists and Reviewer Feedback—default to one typed JSON envelope and use --pretty for human output. The CLI also includes the agent-first Instructions command group, a preview-first Project To-dos and quizzes group, and hosted LMS visual proof that returns real worker-renderer evidence without a local browser.

For a guided first run — register, draft, publish, claim — start with the CLI quickstart. This page covers configuration and conventions; the command reference documents every command.

Install

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

Node.js 18+ is required. One-off runs work too: npx -y @opentrain-ai/cli whoami.

Authentication Modes

There are two ways to get credentials into the CLI:

Register as a new agent (no account needed)

opentrain auth register --agent-name "My agent"

Creates an anonymous agent account via POST /api/agent/identity and saves the pre-claim ot_pat_ token plus the claim token locally. Unlock hiring and other money-adjacent commands later with opentrain auth claim --email <human-email> and opentrain auth claim-status --wait — the claim ceremony.

Log in with an existing token

opentrain auth login --api-key ot_pat_...

Verifies the token against GET /auth/me and saves it. Tokens come from the OpenTrain app’s settings or POST /tokens.

opentrain auth status (alias whoami) shows who you are, the token’s scopes, and the account type at any time.

Credentials File

Credentials are stored at ${XDG_CONFIG_HOME:-~/.config}/opentrain/cli.json with file mode 0600:

{
  "apiToken": "ot_pat_...",
  "baseUrl": "https://app.opentrain.ai",
  "claimToken": "ot_clm_..."
}

claimToken is present only between auth register and a completed claim. The file is shared with the MCP server — registering or logging in through either surface makes the credentials available to both. opentrain auth logout deletes the file.

Credential and Base URL Precedence

For the API token, highest priority first:

1. --api-key on opentrain auth login (the only command that accepts a token flag)
2. OT_API_TOKEN or OPENTRAIN_API_TOKEN environment variable
3. The saved credentials file

For the base URL:

1. --base-url <url> — accepted by every command
2. OT_API_BASE_URL or OPENTRAIN_API_BASE_URL environment variable
3. The saved credentials file, then the default https://app.opentrain.ai

Conventions

• Machine output is deterministic. Legacy families support --json, which prints the raw API response (or, for auth commands, the structured result) as pretty-printed JSON. The checklists and feedback families already print exactly one { "ok": true, "data": ... } envelope by default; --json is a compatibility no-op and --pretty is the only human mode. Do not combine --json and --pretty.
• Errors go to stderr with exit code 1. API failures print OpenTrain API request failed (<status> <code>): <message> plus a Details: line with the error envelope’s details object when present. Usage mistakes print Usage error: ....
• Automatic retries for reads. GET requests retry up to 3 attempts with exponential backoff (500 ms, 1 s) on 502/503/504 and transient network failures. Writes only retry failures where the request never reached the server (DNS errors, connection refused), so a retried write can never duplicate. Request timeout is 30 seconds.
• Idempotency. jobs draft create accepts --idempotency-key; hire and invite commands are idempotent server-side (re-running returns the existing resource).
• Guarded rich-document writes. Instructions writes use stable idempotency keys, checksums, exact no-write preflights, and short-lived signed operation tokens. Use --confirm-live only after reviewing the preflight; whole-page replacement also requires --confirm-replace.
• Guarded assignment fan-out. Project To-do creation and assignment preview by default. Every operation names its audience; broad audiences need both the matching signed receipt and explicit confirmation before the live write.
• Automatic live-job synchronization. CLI 0.11.0+ privately carries the Job Operations session across covered native and bridged commands. Each covered JSON response reports conflicts, recommendations, next operations, and exhaustive syncCoverage; no credential or signed token is printed.

Command Namespaces

Namespace	Commands	What it covers
auth	register, claim, claim-status, login, status, logout (+ top-level whoami)	Agent onboarding, claim ceremony, token management
jobs	draft create, draft update, list, search, publish, invite, close, update-published	Drafting, publishing, and managing jobs
proposals	list, get, hire	Candidate review and hiring
freelancers	get	Masked AI trainer profiles
messages	list, unread, read, send, start-proposal-thread	Conversations and messaging
contracts	list, get, end	Post-hire contracts
milestones	create, fund, approve	Milestones and co-signed money moves
approvals	get	Human co-sign approval status
credits	show, ledger, top-up, top-up-status	Prepaid credit balance and top-ups
updates	poll	The account event delta feed
webhooks	create, list, get, delete	Webhook subscriptions
tokens	list, revoke	API token audit and revocation
team	show, invite	Employer team management
payments	pending	Pending payment reads
instructions	Capabilities, page editing, deterministic DOCX import, local bundle diff/plan/atomic apply, canonical and visual verification	Canonical rich pages in a real job’s Instructions tab
todos	List, create, assign, review, archive, author quizzes, inspect results, grade, release, and require retakes	Canonical Project To-dos and native forms/quizzes for a job
manager	Context, sync polling, priorities, claims, intents, proposals, overlays, policies, managed messages, checkpoints, and handoffs	Shared live-job operations across employer team members and agents
checklists	File-first init, checkout, validate, diff, push, browser preview, publish, order, settings, versions, and submissions	Adaptive per-task checklists for AI trainers and reviewers
feedback	Search, summary, detail, submit, triage, subject roster/linking, reviewer grants, and settings	Employer-private reviewer reports and reviewer access

Each command’s required scope, feature flag, and claim state match the endpoint it wraps — the command reference links every command to its endpoint page.