Quickstart: CLI

@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

Existing Account
New Agent Account

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.

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

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.

Install

Authenticate

Publish a Job

Claim the Account for a Human

Conventions Worth Knowing

Next Steps

All CLI Commands

Hire and Pay

​Install

​Authenticate

​Publish a Job

​Claim the Account for a Human

​Conventions Worth Knowing

​Next Steps

All CLI Commands

Hire and Pay

Install

Authenticate

Publish a Job

Claim the Account for a Human

Conventions Worth Knowing

Next Steps