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

# baseten harness

> Configure Baseten harness integrations (PRE-RELEASE)

<Note>
  PRE-RELEASE: Harness commands are not GA yet and support only macOS and Linux for now. Their arguments, flags, and output may change.
</Note>

Configure Claude Code, Codex (CLI or ChatGPT desktop app), and OpenCode CLI to use Baseten routes.

## setup

```sh theme={"system"}
baseten harness setup [OPTIONS]
```

Configure installed harnesses with your team's routes and a routes API key.

Setup offers a picker of installed harnesses when `--harness` is omitted. Repeat `--harness` to select several. The team's routes with model metadata are added to each harness's model picker, replacing it. Claude Code lists the routes that serve the Anthropic Messages API, and Codex lists the routes that serve the OpenAI Responses API. The first listed route is the default unless `--route` is set.

Setup overwrites the harness's integration settings without saving their previous values. Running it again refreshes them. The routes API key is created on first setup and reused afterward. Restart the harness after setup. For Codex, setup also signs out of OpenAI/ChatGPT and disables ChatGPT login while the Baseten harness is configured, and restarts Codex's background server if one is running, asking first when Codex sessions are attached to it.

### Options

<ParamField body="--background-route" type="TEXT">
  Route for lightweight background tasks (Claude Code and OpenCode). Defaults to deepseek-ai/DeepSeek-V4.1-Flash.
</ParamField>

<ParamField body="--config-dir" type="TEXT">
  Harness configuration directory. Requires exactly one --harness. Defaults to the harness's own location.
</ParamField>

<ParamField body="--dry-run" type="BOOL">
  Preview the configuration without changing files or creating an API key.
</ParamField>

<ParamField body="--fallback-route" type="TEXT">
  Route to fall back to when the default is unavailable (Claude Code). Defaults to the default route.
</ParamField>

<ParamField body="--harness" type="TEXT (repeatable)">
  Harness to apply to. May be repeated.

  One of: `claude-code`, `codex`, `opencode`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--key-name" type="TEXT">
  Name of the routes API key created in Baseten. Defaults to baseten-harness-`hostname`, numbered (-2, -3, ...) if one of your keys has that name.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--route" type="TEXT">
  Default route. Defaults to the first route the harness lists.
</ParamField>

<ParamField body="--subagent-route" type="TEXT">
  Route for subagents (Claude Code and OpenCode). Defaults to the harness's own setting.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID whose routes to use. Defaults to the organization's default team. Run 'baseten org team list' to see teams.
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Configure installed harnesses interactively

```sh theme={"system"}
baseten harness setup
```

Preview configuration for one harness

```sh theme={"system"}
baseten harness setup --harness claude-code --route <route-name> --dry-run
```

Apply a configuration without prompting

```sh theme={"system"}
baseten harness setup --harness codex --team <team> --route <route-name> --yes
```

### Filter output with `--jq`

Print the configuration file paths

```sh theme={"system"}
baseten harness setup --harness claude-code --dry-run --jq '.items[].config'
```

### Output

**Text mode (`--output text`):** The created key and follow-up commands. Use `--dry-run` or `--verbose` for the configuration of each harness, and `--verbose` for setting names.

**JSON mode (`--output json`):** payload type `cmd.HarnessPlanList`.

## status

```sh theme={"system"}
baseten harness status [OPTIONS]
```

Show the installed version, configuration path, and configured routes of each harness. Without `--harness`, shows every harness configured at its default path. Status reads local files only, so it works after the harness is uninstalled, but it doesn't check the key or live routes. Rerun setup to refresh routes.

### Options

<ParamField body="--config-dir" type="TEXT">
  Harness configuration directory. Requires exactly one --harness. Defaults to the harness's own location.
</ParamField>

<ParamField body="--harness" type="TEXT (repeatable)">
  Harness to apply to. May be repeated.

  One of: `claude-code`, `codex`, `opencode`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Inspect Codex configuration

```sh theme={"system"}
baseten harness status --harness codex
```

### Filter output with `--jq`

Print each harness's state

```sh theme={"system"}
baseten harness status --jq '.items[] | {harness, state}'
```

### Output

**Text mode (`--output text`):** Local configuration and configured routes. Use `--verbose` for setting names.

**JSON mode (`--output json`):** payload type `cmd.HarnessStatusList`.

## usage

```sh theme={"system"}
baseten harness usage [OPTIONS]
```

Show your routes spend and token usage for the month so far, the period monthly spend limits apply to.

This is a shortcut for `baseten route usage --user-id <your-user-id> --start <first-of-this-month-utc>` and takes the same flags. The only other difference is the text table, which totals each `--group-by` combination over the window instead of listing each day; JSON output is identical. Organization admins can pass `--user-id` for other users; other members only ever see usage from keys they created.

Usage comes in whole UTC days: `--start` is snapped down to its day and `--end` is rounded up to the end of its day. Every bucket in the window is fetched, paging as needed, until `--limit` buckets are collected.

This is the same spend that spend limits are checked against, and it can lag by up to 15 minutes. Model API costs use your prices and include tool calls. OpenAI, Anthropic, and xAI costs estimate what those providers charge and are not Baseten charges. Vertex and OpenAI-compatible usage isn't included. Usage is retained for 92 days.

For machine-readable streaming, prefer `--output jsonl` over `--output json`.

### Options

<ParamField body="--end" type="TEXT">
  End of the range, exclusive, rounded up to the end of its UTC day. ISO 8601, local when no timezone is given. Defaults to now.
</ParamField>

<ParamField body="--group-by" type="TEXT (repeatable)" default="model">
  Dimension to break usage down by. May be repeated.

  One of: `user`, `model`, `provider`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--limit" type="INTEGER">
  Maximum number of daily buckets, paging as needed. 0 for no limit.
</ParamField>

<ParamField body="--model" type="TEXT (repeatable)">
  Only return usage for these models. May be repeated.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--provider" type="TEXT (repeatable)">
  Only return usage for these providers. May be repeated.

  One of: `baseten-model-api`, `openai`, `anthropic`, `xai`, `vertex`, `openai-compatible`
</ParamField>

<ParamField body="--since" type="TEXT">
  Window from a relative time ago until now (e.g. '7d'). Mutually exclusive with --start and --end.
</ParamField>

<ParamField body="--start" type="TEXT">
  Start of the range, inclusive, snapped down to its UTC day. ISO 8601, local when no timezone is given. Defaults to the start of the current UTC month.
</ParamField>

<ParamField body="--user-id" type="TEXT (repeatable)">
  Only return usage from routes API keys created by these user IDs. May be repeated. Defaults to your own user ID.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Show your usage this month so far, by model

```sh theme={"system"}
baseten harness usage
```

Show usage over the last 7 days by provider

```sh theme={"system"}
baseten harness usage --since 7d --group-by provider
```

Break August's usage down by user and model for two users (admins)

```sh theme={"system"}
baseten harness usage --start 2026-08-01T00:00:00Z --end 2026-09-01T00:00:00Z --group-by user --group-by model --user-id <id> --user-id <id>
```

### Filter output with `--jq`

Stream each day's cost per model as a JSONL stream

```sh theme={"system"}
baseten harness usage --output jsonl --jq '.results[] | {model, cost_usd}'
```

### Output

**Text mode (`--output text`):** Table with one column per `--group-by` dimension, then INPUT, CACHED, and OUTPUT token counts and COST, totaled over the window, most expensive first, followed by an ALL totals row. A cost of "-" means some of that usage couldn't be priced. The window goes to stderr. With no usage in the window, prints "No usage in the selected window." to stderr instead of a table.

**JSON mode (`--output json`):** payload type `managementapi.RoutesUsageBucket`.

One record per UTC day, as returned by the API: its date and the per-dimension usage in results, including days with no usage. cost\_usd values are exact decimal strings.

## teardown

```sh theme={"system"}
baseten harness teardown [OPTIONS]
```

Remove the Baseten integration settings so the harness's own defaults apply. Previous values are not restored, and unrelated settings are kept. Without `--harness`, removes every integration configured at its default path.

Teardown also deletes the routes API key the removed harnesses use, once no other harness on this machine uses it. It works after the harness is uninstalled. For Codex, teardown re-enables ChatGPT login and restarts Codex's background server if one is running, asking first when Codex sessions are attached to it. Run `codex login` to sign back in.

### Options

<ParamField body="--config-dir" type="TEXT">
  Harness configuration directory. Requires exactly one --harness. Defaults to the harness's own location.
</ParamField>

<ParamField body="--dry-run" type="BOOL">
  Preview removal without changing files.
</ParamField>

<ParamField body="--harness" type="TEXT (repeatable)">
  Harness to apply to. May be repeated.

  One of: `claude-code`, `codex`, `opencode`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Preview removal

```sh theme={"system"}
baseten harness teardown --harness codex --dry-run
```

Remove integration settings without prompting

```sh theme={"system"}
baseten harness teardown --harness codex --yes
```

### Filter output with `--jq`

List the settings teardown would remove

```sh theme={"system"}
baseten harness teardown --dry-run --jq '.items[].settings'
```

### Output

**Text mode (`--output text`):** The settings removed from each harness. Use `--verbose` for configuration paths and setting names.

**JSON mode (`--output json`):** payload type `cmd.HarnessPlanList`.