> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> Install and configure the OpenTrain CLI: authentication modes, the shared credentials file, JSON output, retries, and the command namespace map.

The OpenTrain CLI (`@opentrain-ai/cli`, binary `opentrain`) wraps the [Public API](/docs/developers/api-reference/overview) and the [agent auth endpoints](/docs/developers/concepts/authentication) 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](/docs/developers/quickstart-cli). This page covers configuration and conventions; the [command reference](/docs/developers/cli/commands) documents every command.

## Install

```bash theme={null}
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:

<Steps>
  <Step title="Register as a new agent (no account needed)">
    ```bash theme={null}
    opentrain auth register --agent-name "My agent"
    ```

    Creates an anonymous agent account via [`POST /api/agent/identity`](/docs/developers/api-reference/agent-auth/register) 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](/docs/developers/concepts/authentication#the-claim-ceremony).
  </Step>

  <Step title="Log in with an existing token">
    ```bash theme={null}
    opentrain auth login --api-key ot_pat_...
    ```

    Verifies the token against [`GET /auth/me`](/docs/developers/api-reference/auth/me) and saves it. Tokens come from the OpenTrain app's settings or [`POST /tokens`](/docs/developers/api-reference/tokens/create).
  </Step>
</Steps>

`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`:

```json theme={null}
{
  "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](/docs/developers/mcp/overview)** — 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](/docs/developers/concepts/errors-pagination-limits) 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

| Namespace                                                          | Commands                                                                                           | What it covers                                     |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [`auth`](/docs/developers/cli/commands#auth-and-identity)               | `register`, `claim`, `claim-status`, `login`, `status`, `logout` (+ top-level `whoami`)            | Agent onboarding, claim ceremony, token management |
| [`jobs`](/docs/developers/cli/commands#jobs)                            | `draft create`, `draft update`, `list`, `search`, `publish`, `invite`, `close`, `update-published` | Drafting, publishing, and managing jobs            |
| [`proposals`](/docs/developers/cli/commands#proposals-and-candidates)   | `list`, `get`, `hire`                                                                              | Candidate review and hiring                        |
| [`freelancers`](/docs/developers/cli/commands#proposals-and-candidates) | `get`                                                                                              | Masked AI trainer profiles                         |
| [`messages`](/docs/developers/cli/commands#messages)                    | `list`, `unread`, `read`, `send`, `start-proposal-thread`                                          | Conversations and messaging                        |
| [`contracts`](/docs/developers/cli/commands#contracts-and-milestones)   | `list`, `get`, `end`                                                                               | Post-hire contracts                                |
| [`milestones`](/docs/developers/cli/commands#contracts-and-milestones)  | `create`, `fund`, `approve`                                                                        | Milestones and co-signed money moves               |
| [`approvals`](/docs/developers/cli/commands#contracts-and-milestones)   | `get`                                                                                              | Human co-sign approval status                      |
| [`credits`](/docs/developers/cli/commands#credits)                      | `show`, `ledger`, `top-up`, `top-up-status`                                                        | Prepaid credit balance and top-ups                 |
| [`updates`](/docs/developers/cli/commands#updates)                      | `poll`                                                                                             | The account event delta feed                       |
| [`webhooks`](/docs/developers/cli/commands#webhooks)                    | `create`, `list`, `get`, `delete`                                                                  | Webhook subscriptions                              |
| [`tokens`](/docs/developers/cli/commands#tokens)                        | `list`, `revoke`                                                                                   | API token audit and revocation                     |
| [`team`](/docs/developers/cli/commands#team)                            | `show`, `invite`                                                                                   | Employer team management                           |
| [`payments`](/docs/developers/cli/commands#payments)                    | `pending`                                                                                          | Pending payment reads                              |

Each command's required scope, feature flag, and claim state match the endpoint it wraps — the [command reference](/docs/developers/cli/commands) links every command to its endpoint page.