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

# CLI and MCP server: run Kite from a terminal or an AI agent

> Install the kite CLI to augment datasets, build twins, and train RL policies from your terminal, or connect the Kite MCP server so Claude, Cursor, or any MCP client can do it for you.

Kite ships two clients for the Platform API:

* **`kite`**, a command-line tool for your terminal and scripts.
* **The Kite MCP server**, which gives AI agents such as Claude Code, Claude, and Cursor the same actions as native tools.

Both call `https://api.kiteml.com/v1` with your account, so anything you start from one shows up in the other and in the [dashboard](https://app.kiteml.com).

## Install the CLI

The CLI is published on PyPI as [`kiteml-cli`](https://pypi.org/project/kiteml-cli/) and needs Python 3.10 or later.

```bash theme={"system"}
pip install "kiteml-cli[mcp]"
```

This installs two commands: `kite`, the CLI, and `kite-mcp`, the MCP server for running it locally. Drop `[mcp]` if you only want the CLI.

## Sign in

```bash theme={"system"}
kite auth login
```

This opens the dashboard in your browser. Click **Authorize CLI** and the CLI receives an API key named `CLI on <your machine>`. It's valid for 90 days and stored in `~/.kite/credentials.json`. You can revoke it any time from **Platform API → API keys**.

On a server or in CI, skip the browser and set an [API key](/platform-api/authentication) instead:

```bash theme={"system"}
export KITE_API_KEY=kite_aBcDeFgH...
```

`KITE_API_KEY` takes precedence over a stored login. To check your setup, run `kite doctor`. It confirms the API is reachable and your key is valid, and exits non-zero if either check fails.

| Command | What it does |
| - | - |
| `kite auth login` | Sign in through the browser. `--headless` prompts you to paste an API key instead. |
| `kite auth whoami` | Show the account you're signed in as. |
| `kite auth logout` | Delete the stored key from this machine. |
| `kite doctor` | Check connectivity and authentication. |
| `kite config show` | Show the CLI's settings, stored in `~/.kite/config.json`. |

## Use the CLI

Every command prints JSON: `{"ok": true, "data": …}` on success, or `{"ok": false, "error": …}` with exit code `1` on failure. Pipe it to `jq` in scripts. Commands that start long-running work take `--wait` to poll until the work finishes.

Run `kite --help` or `kite <command> --help` to see every option.

### Augmentations

```bash theme={"system"}
kite augment create \
  --repo-id lerobot/pusht \
  -i "change the table surface to white marble, vary the lighting" \
  -n 20 \
  --wait

kite augment download aug_01J8X4... -o ./pusht-marble
```

`download` writes the dataset to disk with its LeRobot layout intact. To deliver to Hugging Face instead, pass `--output huggingface --hf-repo your-org/pusht-marble`. `--model relight` forces relighting, and `--reference-image` gives Kite a photo of the look to match. See [Augmentations](/platform-api/augmentation) for when to use each.

| Command | What it does |
| - | - |
| `kite augment create` | Start an augmentation. |
| `kite augment status <id>` | Status, progress and, once done, output files. |
| `kite augment list` | Your augmentations, newest first. |
| `kite augment cancel <id>` | Cancel a running augmentation. Unproduced episodes are refunded. |
| `kite augment download <id>` | Download a finished `download` augmentation. |

### Twins

<Note>
  Twins are in private beta and enabled per account. See [Twins](/platform-api/twins).
</Note>

```bash theme={"system"}
kite twin validate lerobot/svla_so101_pickplace
kite twin create lerobot/svla_so101_pickplace --out ./twins
```

A twin takes about 100 minutes. With `--out`, the command waits, then downloads the archive, verifies its checksum, and unpacks it to `./twins/<twin id>/scene.xml`.

| Command | What it does |
| - | - |
| `kite twin validate <dataset>` | Free check of a dataset. Creates nothing. |
| `kite twin create <dataset>` | Build a twin from one episode. |
| `kite twin status <id>` | Status, stage and progress. |
| `kite twin list` | Your twins, newest first. |
| `kite twin files <id>` | The files in a finished twin's archive. |
| `kite twin cancel <id>` | Stop a twin. Finished stages stay cached. |
| `kite twin resume <id>` | Re-queue a failed or canceled twin from where it stopped. |
| `kite twin download <id>` | Download, verify, and unpack a finished twin. |

### RL runs

Describe the behavior in plain words, check the spec for free, then train:

```bash theme={"system"}
kite rl plan open_duck_mini_v2 "walk forward at a steady pace" -o walk.json
kite rl validate walk.json
kite rl train walk.json --budget probe --wait
kite rl download rlr_01J8X4... -o .
```

`plan` writes a task spec you can edit. `validate` compiles it and reports what each reward term pays three canned policies, at no cost. `--budget probe` trains for 300 iterations to give a first signal in minutes. `download` unpacks the bundle to `./kiteml_<run id>/`, with the policy at `policy/policy.onnx`. See [RL runs](/platform-api/rl-runs) for the spec and the bundle.

| Command | What it does |
| - | - |
| `kite rl catalog` | Robots, objectives with their parameters, hardware, and budget presets. |
| `kite rl plan <robot> <prompt>` | A task spec from a description. Creates nothing. |
| `kite rl validate <spec>` | Free check of a spec in seconds. |
| `kite rl estimate <spec>` | Minutes and tokens per run. |
| `kite rl train <spec>` | Start one run per seed (`--seeds`, 1–5). |
| `kite rl status <id>` | Status, phase, progress and metrics. |
| `kite rl metrics <id>` | The training curve. |
| `kite rl report <id>` | The verdict and each check behind it. |
| `kite rl list` | Your runs, newest first. |
| `kite rl files <id>` | Every file in a packaged run's bundle. |
| `kite rl download <id>` | Download and unpack the bundle. |
| `kite rl checkpoints <id>` | The iterations the run saved. |
| `kite rl checkpoint <id>` | Download one saved iteration. |
| `kite rl cancel <id>` | Stop a run. A run that started training keeps its policy so far. |
| `kite rl fork <id>` | Train from a run's weights with the parameters you `--set`. |
| `kite rl continue <id>` | Keep training a run from where it stopped. |

## Connect the MCP server

The MCP server lets an AI agent drive Kite for you. Ask Claude to "relight lerobot/pusht to match this photo" or "train the Open Duck to walk and tell me when it passes", and it calls Kite's tools, polls the work, and reports back.

Kite hosts the server at `https://mcp.kiteml.com/mcp`, so there's nothing to install.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"system"}
    claude mcp add --transport http kite https://mcp.kiteml.com/mcp
    ```

    The first time Claude uses a Kite tool, your browser opens to sign in to Kite. To authenticate with an API key instead, for example in CI:

    ```bash theme={"system"}
    claude mcp add --transport http kite https://mcp.kiteml.com/mcp \
      --header "Authorization: Bearer $KITE_API_KEY"
    ```
  </Tab>

  <Tab title="Claude">
    In Claude or Claude Desktop, open **Settings → Connectors**, click **Add custom connector**, and enter:

    ```text theme={"system"}
    https://mcp.kiteml.com/mcp
    ```

    Claude opens a Kite sign-in window to connect your account.
  </Tab>

  <Tab title="Cursor and others">
    Add the server to your client's MCP configuration, for example `~/.cursor/mcp.json`:

    ```json theme={"system"}
    {
      "mcpServers": {
        "kite": {
          "url": "https://mcp.kiteml.com/mcp"
        }
      }
    }
    ```

    Clients that support MCP OAuth sign you in through the browser. Otherwise, add `"headers": { "Authorization": "Bearer kite_..." }` with your API key.
  </Tab>
</Tabs>

### Run it locally

The hosted server can't read or write files on your machine. When a twin or RL run finishes, its tools return the exact `curl` command to download the output, and your agent runs it. To give the server direct access to local files, for example to pass a reference photo by path, run it on your machine with the CLI installed:

```bash theme={"system"}
claude mcp add kite -e KITE_API_KEY=$KITE_API_KEY -- kite-mcp
```

The local server reads `KITE_API_KEY` from its environment and runs over stdio.

### Tools

Every tool returns `{"ok": true, "data": …}` or `{"ok": false, "error": …}`. Status tools for twins and RL runs add a `next` field that tells the agent what to do now: wait and check again, read the report, or run the download command.

| Tools | What they do |
| - | - |
| `kite_augment_create`, `kite_augment_status`, `kite_augment_list`, `kite_augment_cancel` | Create and follow [augmentations](/platform-api/augmentation). |
| `kite_twin_validate`, `kite_twin_create`, `kite_twin_status`, `kite_twin_list`, `kite_twin_cancel`, `kite_twin_resume` | Check a dataset, then build and follow [twins](/platform-api/twins). |
| `kite_rl_catalog`, `kite_rl_plan`, `kite_rl_validate` | Explore what RL runs can train, and plan and check a spec for free. |
| `kite_rl_train`, `kite_rl_fork`, `kite_rl_cancel` | Start, branch from, and stop [RL runs](/platform-api/rl-runs). |
| `kite_rl_status`, `kite_rl_metrics`, `kite_rl_report`, `kite_rl_list` | Follow RL runs and read their verdicts. |
| `kite_doctor` | Check connectivity and authentication. |

Tools that only read are marked read-only, and tools that cancel work are marked destructive, so your client can ask before running them. Work the agent starts is charged to your account like any other request.

<Tip>
  Need help? Reach out at [raul@kiteml.com](mailto:raul@kiteml.com).
</Tip>