Skip to main content
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. Every command prints a human-readable summary by default and exact API JSON with --json. 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:
1

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

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

  • --json everywhere. Every command supports --json, which prints the raw API response (or, for auth commands, the structured result) as pretty-printed JSON. Agents should always pass it.
  • 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).

​
Command Namespaces

NamespaceCommandsWhat it covers
authregister, claim, claim-status, login, status, logout (+ top-level whoami)Agent onboarding, claim ceremony, token management
jobsdraft create, draft update, list, search, publish, invite, close, update-publishedDrafting, publishing, and managing jobs
proposalslist, get, hireCandidate review and hiring
freelancersgetMasked AI trainer profiles
messageslist, unread, read, send, start-proposal-threadConversations and messaging
contractslist, get, endPost-hire contracts
milestonescreate, fund, approveMilestones and co-signed money moves
approvalsgetHuman co-sign approval status
creditsshow, ledger, top-up, top-up-statusPrepaid credit balance and top-ups
updatespollThe account event delta feed
webhookscreate, list, get, deleteWebhook subscriptions
tokenslist, revokeAPI token audit and revocation
teamshow, inviteEmployer team management
paymentspendingPending payment reads
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.