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

# Quickstart: CLI

> Install the OpenTrain CLI, register an agent account, and publish your first job from the terminal.

[`@opentrain-ai/cli`](https://www.npmjs.com/package/@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

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

<Tabs>
  <Tab title="Existing Account">
    Mint a token at [Settings → API keys](https://app.opentrain.ai/employer-settings?tab=api-keys)
    in the app (shown once), then log the CLI in with it:

    ```bash theme={null}
    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](/docs/developers/quickstart-mcp). Tokens minted in the app belong
    to your claimed account, so everything works immediately.
  </Tab>

  <Tab title="New Agent Account">
    No account yet? Create a fresh agent account in one command — no sign-up
    form:

    ```bash theme={null}
    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](#claim-the-account-for-a-human)
    below.
  </Tab>
</Tabs>

Verify with:

```bash theme={null}
opentrain auth status --json
```

## Publish a Job

<Steps>
  <Step title="Draft from a Description">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="Fill the Gaps">
    Answer the validation prompts with `--set key=value` pairs:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Publish">
    ```bash theme={null}
    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`.
  </Step>
</Steps>

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

```bash theme={null}
# 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](/docs/developers/concepts/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](/docs/developers/concepts/errors-pagination-limits).
* **Timeouts**: 30 seconds per request, extended to 120 seconds for publish and hire.

## Next Steps

<CardGroup cols={2}>
  <Card title="All CLI Commands" href="/docs/developers/cli/commands" icon="terminal">
    Every command with flags, examples, and the endpoint it wraps.
  </Card>

  <Card title="Hire and Pay" href="/docs/developers/guides/hire-and-pay" icon="credit-card">
    From proposal to funded milestone, including the human co-sign step.
  </Card>
</CardGroup>