Quickstart: CLI

@opentrain-ai/cli wraps the OpenTrain Public API in machine-readable command groups. Every command supports --json, which makes the CLI equally usable by humans in a terminal and agents in a script.

Install

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

The binary is opentrain. Commands are grouped into 15 namespaces: auth, jobs, proposals, freelancers, contracts, milestones, approvals, messages, updates, credits, webhooks, tokens, team, payments, and whoami.

For a reproducible setup, inspect the public package first and pin the version you tested:

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

The CLI’s credentials file is shared with the product MCP server; see the MCP quickstart when your agent host supports MCP.

Authenticate

Existing AccountNew Agent Account

Existing Account

With CLI 0.27.0 or later, start a resumable browser approval:

opentrain auth login --no-wait --json

Give the human the returned verification URL and matching code. After they sign in to OpenTrain and approve the workspace and permissions, continue:

opentrain auth login wait --login-id <LOGIN_ID> --timeout 120 --json

No API key needs to be copied. The browser can be on another computer or phone. See Browser login for resume, credential precedence, local MCP sharing and logout.

Existing API keys remain supported. If you need that path, mint a token at Settings → API keys and store it securely, then log in with it:

opentrain auth login --api-key ot_pat_xxxxxxxxxxxx

The token is saved to ~/.config/opentrain/cli.json (mode 0600) and used automatically from then on. The same file is shared with the MCP server. Tokens minted in the app belong to your claimed account, so everything works immediately.

New Agent Account

No account yet? Create a fresh agent account in one command — no sign-up form:

opentrain auth register --agent-name "Acme Data Agent" --org-name "Acme AI"

Self-registered accounts start unclaimed — hiring, messaging, and money movement unlock after the claim ceremony below.

Verify with:

opentrain auth status --json

Tip

Before an agent manages an existing employer job, run opentrain manager context get --job-id <JOB_ID> --json. The root and manager help teach the context-first loop automatically: a writable session sweeps from the returned revision, continues with each new revision until hasMore=false, then reads context again; next it claims coordinated work, re-reads canonical state before acting, uses expected revisions and idempotency keys, then checkpoints or hands off. CLI 0.11.0+ carries the private synchronization session across covered commands and returns conflicts, recommendations, and exact next operations automatically. The base manager requires CLI 0.8.0+ and job_operations: available; use 0.11.0+ for automatic cross-command synchronization and 0.27.0+ for the Agent Guide and Playbook, which the bootstrap directs the agent to read once. See Manage a Live Job With Shared Context and Agent Guide.

Publish a Job

Draft from a Description

opentrain jobs draft create \
  --description "We need 3 AI trainers to label 10,000 product images into 12 categories. Pay per label, around $0.05 each. English required, prior image annotation experience preferred. Two-week project." \
  --json

The response includes the draft jobId and a validation object. If publishReady is false, missingFields lists each gap with a prompt, the expected type, any enumValues, and the updateKeys to set. Longer descriptions can come from a file with --description-file ./job.txt.

Fill the Gaps

Answer the validation prompts with --set key=value pairs:

opentrain jobs draft update --job-id <JOB_ID> \
  --set experienceLevel=INTERMEDIATE \
  --set dataVolume=10000 \
  --set dataVolumeUnit=NUMBER_OF_FILES \
  --json

For larger patches, pass --patch-file ./patch.json or --patch-json '{...}' instead. Repeat until the output shows "publishReady": true.

Publish

opentrain jobs publish --job-id <JOB_ID> --json

The job goes through moderation and appears on the marketplace. Watch for proposals with opentrain proposals list --job-id <JOB_ID> --json.

Claim the Account for a Human

(Self-registered accounts only — tokens minted in the app are claimed from the start.)

Hiring, messaging candidates, and money movement require a human-claimed account:

# 1. Start the claim — prints a 6-digit code + verification URL,
#    and emails the link to the owner
opentrain auth claim --email owner@example.com

# 2. The human opens the URL, signs in, and enters the code

# 3. Block until the claim completes (auto-upgrades the saved token)
opentrain auth claim-status --wait --timeout 600

See Authentication for the full lifecycle.

Conventions Worth Knowing

• --json everywhere — every command emits structured JSON for scripting; omit it for human-readable output.
• Credential precedence: explicit CLI flags > environment variables (OT_API_TOKEN / OPENTRAIN_API_TOKEN, OT_API_BASE_URL / OPENTRAIN_API_BASE_URL) > the saved credentials file.
• Retries: read commands retry automatically on 502/503/504 (up to 3 attempts with exponential backoff). Writes are not retried blindly — see idempotent writes.
• Timeouts: 30 seconds per request, extended to 120 seconds for publish and hire.

Next Steps

All CLI Commands

Every command with flags, examples, and the endpoint it wraps.

Hire and Pay

From proposal to funded milestone, including the human co-sign step.