Skip to main content
@opentrain-ai/cli wraps the full OpenTrain Public API in ~43 commands. Every command supports --json for machine-readable output, 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.

​
Authenticate

Mint a token at Settings → API keys in the app (shown once), then log the CLI 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.
Verify with: 
opentrain auth status --json

​
Publish a Job

1

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.
2

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.
3

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.