OpenTrain CLI

Command-line client for the OpenTrain public API. Built for coding agents and scripts: register an agent account, draft and publish jobs, review proposals, hire freelancers, manage contracts and milestones, message, poll updates or register webhooks, and manage credits and your team — all from the terminal.

Money never moves from the CLI: hire, milestone funding/approval, and contract-end requests record a pending approval and return an approvalUrl that a signed-in human must open and confirm in the OpenTrain app.

Install

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

Or run without installing:

npx @opentrain-ai/cli whoami

Quick start (agent onboarding — no human account needed)

# 1. Create an anonymous agent account with a pre-claim API token
#    (job drafting/publishing + read access). Saved to local config.
opentrain auth register --agent-name "My Agent"

# 2. Draft a job from a plain-text description — OpenTrain parses it
opentrain jobs draft create --description-file ./job-description.txt

# 3. Fill any missing fields the draft output asks for
opentrain jobs draft update --job-id <id> --set pricePerHour=25

# 4. Publish when the draft is publish ready
opentrain jobs publish --job-id <id>

# 5. To unlock hiring, messaging, and team invites, hand the account to a human:
opentrain auth claim --email [email protected]
opentrain auth claim-status --wait

Already have a personal API token (ot_pat_…) from the OpenTrain app?

opentrain auth login --api-key ot_pat_<publicId>_<secret>
opentrain whoami

Commands

opentrain --version
opentrain whoami [--json]
opentrain auth register [--agent-name <name>] [--org-name <name>] [--base-url <url>] [--force] [--json]
opentrain auth claim --email <human-email> [--claim-token <token>] [--json]
opentrain auth claim-status [--wait] [--timeout <seconds>] [--claim-token <token>] [--json]
opentrain auth login --api-key <token> [--base-url <url>]
opentrain auth status [--json]
opentrain auth logout
opentrain jobs draft create --description <text> [--title <title>] [--external-id <id>] [--idempotency-key <key>] [--json]
opentrain jobs draft create --description-file <path> [--title <title>] [--external-id <id>] [--idempotency-key <key>] [--json]
opentrain jobs draft create --canonical-file <path> [--external-id <id>] [--idempotency-key <key>] [--json]
opentrain jobs draft create --payload-file <path> [--external-id <id>] [--idempotency-key <key>] [--json]
opentrain jobs draft update --job-id <id> --set <field=value> [--set <field=value> ...] [--json]
opentrain jobs draft update --job-id <id> --patch-file <path> | --patch-json <json> [--json]
opentrain jobs list [--status <status>] [--limit <n>] [--cursor <cursor>] [--json]
opentrain jobs search [--q <text>] [--category <slug>] [--language <lang>] [--country <iso>] [--pay-type PAY_PER_HOUR|FIXED_PRICE|PAY_PER_LABEL] [--limit <n>] [--cursor <cursor>] [--json]
opentrain jobs publish --job-id <id> [--json]
opentrain jobs invite --job-id <id> --freelancer-id <id> [--json]
opentrain jobs close --job-id <id> [--json]
opentrain jobs update-published --job-id <id> --set <field=value> [--set <field=value> ...] [--json]
opentrain jobs update-published --job-id <id> --patch-file <path> | --patch-json <json> [--json]
opentrain contracts list [--job-id <id>] [--status active|ended] [--json]
opentrain contracts get --contract-id <id> [--json]
opentrain contracts end --contract-id <id> [--json]
opentrain milestones create --contract-id <id> --description <text> [--name <name>] [--amount <usd>] [--volume <n>] [--due-date <iso>] [--json]
opentrain milestones fund --milestone-id <id> [--json]
opentrain milestones approve --milestone-id <id> [--json]
opentrain approvals get --approval-id <id> [--json]
opentrain proposals list --job-id <id> [--status <status>] [--limit <n>] [--cursor <cursor>] [--json]
opentrain proposals get --proposal-id <id> [--interview] [--json]
opentrain proposals hire --proposal-id <id> --amount <usd> [--milestone-name <name>] [--milestone-description <text>] [--due-date <iso>] [--confirm-not-fit-override] [--json]
opentrain freelancers get --id <user-id-or-slug> [--json]
opentrain messages list [--filter all|job|proposal] [--unread-only] [--limit <n>] [--cursor <cursor>] [--json]
opentrain messages unread [--filter all|job|proposal] [--limit <n>] [--cursor <cursor>] [--json]
opentrain messages read --conversation-id <id> [--limit <n>] [--direction older|newer] [--cursor <cursor>] [--json]
opentrain messages send --conversation-id <id> --content <text> [--json]
opentrain messages send --conversation-id <id> --content-file <path> [--json]
opentrain messages start-proposal-thread --proposal-id <id> [--json]
opentrain updates poll [--cursor <cursor>] [--limit <n>] [--json]
opentrain credits show [--json]
opentrain credits ledger [--cursor <cursor>] [--limit <n>] [--json]
opentrain credits top-up --amount <usd> [--json]
opentrain credits top-up-status --top-up-id <id> [--json]
opentrain webhooks create --url <url> --events <type,...> [--json]
opentrain webhooks list [--json]
opentrain webhooks get <webhook-id> [--json]
opentrain webhooks delete <webhook-id> [--json]
opentrain tokens list [--json]
opentrain tokens revoke --token-id <id> [--json]
opentrain team show [--json]
opentrain team invite --email <address> [--json]
opentrain payments pending [--json]

Pass --json on any command for the exact API response body (best for agents and scripts).

Job drafting & publishing

Draft create is the primary workflow. Send a normal job description (inline or from a file); OpenTrain parses it server-side into structured job fields and returns an unpublished draft URL plus validation state:

cat > /tmp/job.txt <<'EOF'
We need experienced image annotation specialists to draw bounding boxes around
retail products in catalog photos. The dataset has about 1,200 JPG files.
Contributors should have prior image labeling or QA experience, write short
notes for edge cases, and report daily throughput. Pay is $25 per hour.
EOF

opentrain jobs draft create --description-file /tmp/job.txt

When the draft is not publish ready, each missing field in the output includes an ask: question to relay to the human, the value type, allowed enum values, and the field name(s) to set. Fill gaps one field at a time:

opentrain jobs draft update --job-id <id> --set aiInterviewRequirements="Explain your QA process"

Numbers, booleans, and JSON arrays are auto-coerced; everything else stays a string. Repeat until publish ready, then:

opentrain jobs publish --job-id <id>

Publishing runs the same validation + moderation pipeline as the in-app flow and is subject to per-account daily publish limits. Structured source systems can use --canonical-file or --payload-file instead of a plain description.

Proposals, hiring, and messaging

# Rank candidates for a job (bid, status, AI-interview and match-score signals)
opentrain proposals list --job-id <id>

# Full candidate evaluation: bid, AI-interview score + summary, location and
# identity verification, Open Label assessment, and contract state.
# --interview appends the sanitized AI-interview transcript.
opentrain proposals get --proposal-id <id> --interview

# Masked freelancer profile by user id or public profile slug: skills, stats,
# work/label experience, education, reviews, languages. Names stay masked to
# first name + last initial; personal contact details (including personal
# email) are never returned.
opentrain freelancers get --id <user-id-or-slug>

# Hire request: does NOT hire or move money. Records a pending approval and
# returns an approvalUrl a signed-in human must open and confirm in the
# OpenTrain app (~72h expiry). Requires a claimed account + payment method or
# covering credit balance — a 409 response includes a billingUrl for the human.
opentrain proposals hire --proposal-id <id> --amount 500

# Open the pre-hire DM thread for a proposal
opentrain messages start-proposal-thread --proposal-id <id>

# Invite a freelancer to a published job
opentrain jobs invite --job-id <id> --freelancer-id <id>

# Conversations and messages
opentrain messages list --filter all --limit 20
opentrain messages read --conversation-id <id> --limit 50
opentrain messages send --conversation-id <id> --content "Thanks — looks great."

Message reads are read-only: they do not create conversations, mark messages read, or return raw attachment URLs. Sending requires a claimed account.

Contracts and milestones (co-signed money movement)

# Contract status, milestones with funding/approval state, budget consumption,
# and the post-hire job DM conversationId
opentrain contracts list --status active
opentrain contracts get --contract-id <id>

# Add an unfunded milestone directly (no money moves)
opentrain milestones create --contract-id <id> --description "Batch 2: 5,000 labels" --amount 250

# Funding and approval record a pending approval and return an approvalUrl —
# a signed-in human confirms in the OpenTrain app before money is held or released
opentrain milestones fund --milestone-id <id>
opentrain milestones approve --milestone-id <id>
opentrain approvals get --approval-id <id>

# Ending a contract is direct when no funded milestones exist; otherwise it
# returns an approval the human must confirm
opentrain contracts end --contract-id <id>

Updates feed and webhooks

# Cursor-based delta feed: new proposals, messages, contract/milestone
# changes, approval confirmations, budget state changes. Persist the returned
# nextCursor and pass it on the next poll.
opentrain updates poll --cursor <nextCursor>

# Or push: signed HMAC webhook deliveries of the same events. The signing
# secret is shown once at creation.
opentrain webhooks create --url https://example.com/hooks/opentrain --events proposal.created,approval.confirmed
opentrain webhooks list

Credits (prepaid balance)

opentrain credits show
opentrain credits ledger

# Returns a Stripe Checkout URL a human completes — the agent cannot pay
opentrain credits top-up --amount 500
opentrain credits top-up-status --top-up-id <id>

Team and payments

opentrain team show
opentrain team invite --email [email protected]
opentrain payments pending
opentrain tokens list

payments pending is read-only and cannot fund, approve, refund, release, or move money.

Configuration

• Saved config: ~/.config/opentrain/cli.json (or $XDG_CONFIG_HOME/opentrain/cli.json), shared with the OpenTrain MCP server (@opentrain-ai/mcp) — registering through either surface makes the credentials available to both.
• Env overrides: OT_API_TOKEN / OPENTRAIN_API_TOKEN and OT_API_BASE_URL / OPENTRAIN_API_BASE_URL.
• Default base URL: https://app.opentrain.ai.

Reliability

Requests time out after 30 seconds (publish and hire get 120 seconds). The CLI automatically retries transient failures with exponential backoff (up to 3 attempts): reads (GET) retry on 502/503/504 gateway errors and network failures; writes retry only on errors that occur before the request reaches the server (connection refused, DNS failures), so a write is never sent twice.

Development (monorepo)

npm install
npm run build -w @opentrain-ai/cli
npm exec -w @opentrain-ai/cli opentrain -- whoami