> ## 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 grid > Manage Baseten Grid (PRE-RELEASE) Configure harness integrations and manage routes with Baseten Grid. > [!NOTE] > > Grid commands are in pre-release and support macOS and Linux. Their arguments, flags, and output can change. ## setup ```sh theme={"system"} baseten grid setup [OPTIONS] ``` Configure installed harnesses with your team's routes and a Grid API key. If you omit `--harness`, setup lets you select from the harnesses installed on your machine. Repeat `--harness` to configure several. Setup replaces each harness's model picker with your team's routes and their model metadata. Claude Code lists routes that serve the Anthropic Messages API, while Codex lists routes that serve the OpenAI Responses API. An explicit `--primary-route-id` takes precedence over the team's default for that harness. Without either, setup uses the first compatible route. Run `baseten grid route list` to find route IDs. Harness configurations store the corresponding route names. The primary route handles the harness's main work. Claude Code and OpenCode can use a separate background route for lightweight tasks and a separate subagent route. Claude Code can also use a fallback route when its primary route is unavailable. Primary and background routes use team defaults when available. An omitted subagent route keeps the harness's own setting, and an omitted Claude Code fallback uses the primary route. Setup replaces the harness's existing integration settings without saving their previous values. Running setup again refreshes those settings. The first setup creates a Grid API key, which later runs reuse. With `--use-session-credential`, setup installs the session's API key instead. The CLI never creates, rotates, or deletes that session key. Setup records the team and options so `baseten grid sync` can replay them. Restart the harness after setup. For Codex, setup signs you out of OpenAI or ChatGPT and disables ChatGPT login while the harness uses the Baseten integration. If the Codex background server is running, setup restarts it. When the server has attached Codex sessions, setup asks for confirmation first. For OpenCode, setup writes the original settings format that OpenCode 1 and 2 both support. If the file already uses OpenCode 2's native settings, setup preserves that format. ### Options **--background-route-id** `TEXT` Route ID for lightweight background tasks (Claude Code and OpenCode). Defaults to the team's default for the harness, else deepseek-ai/DeepSeek-V4.1-Flash. **--config-dir** `TEXT` Harness configuration directory. Requires exactly one `--harness`. Defaults to the harness's own location. **--dry-run** `BOOL` Preview the configuration without changing files or creating an API key. **--fallback-route-id** `TEXT` Route ID to fall back to when the default is unavailable (Claude Code). Defaults to the primary route. **--harness** `TEXT (repeatable)` Harness to apply to. May be repeated. One of: `claude-code`, `codex`, `opencode`, `pi` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--key-name** `TEXT` Name of the Grid API key, if setup creates one. Defaults to baseten-harness-`hostname`-`random suffix`. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--primary-route-id** `TEXT` Primary route ID. Defaults to the team's default for the harness, else the first route the harness lists. **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--subagent-route-id** `TEXT` Route ID for subagents (Claude Code and OpenCode). Defaults to the harness's own setting. **--team** `TEXT` Team name or ID whose routes to use. Omit to let the API select your only team. Run 'baseten org team list' to see teams. **--use-session-credential** `BOOL` Install the session's API key (BASETEN\_API\_KEY or an API-key profile) as the harness credential instead of creating a Grid API key. The key is never created, rotated, or deleted by this CLI. Mutually exclusive with `--key-name`. **--yes** `BOOL` Skip the interactive confirmation prompt. Required when stdin is not a terminal. **-v, --verbose** `BOOL` Enable verbose logging ### Examples Configure installed harnesses interactively: ```sh theme={"system"} baseten grid setup ``` Install a pre-minted key from the environment instead of creating one: ```sh theme={"system"} baseten grid setup --harness claude-code --use-session-credential --yes ``` Preview configuration for one harness: ```sh theme={"system"} baseten grid setup --harness claude-code --primary-route-id --dry-run ``` Apply a configuration without prompting: ```sh theme={"system"} baseten grid setup --harness codex --team --primary-route-id --yes ``` ### Filter output with `--jq` Print the configuration file paths: ```sh theme={"system"} baseten grid 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`):** Returns an `items` array with the setup plan for each selected harness. ## sync ```sh theme={"system"} baseten grid sync [OPTIONS] ``` Reapply every harness configuration on this machine with the team, location, and options recorded by its last `baseten grid setup` command. Sync doesn't accept a harness selection. To change the selection, run `baseten grid setup` or `baseten grid teardown`. If the team removed a stored route, sync falls back to the default route and prints a warning. Sync updates only harnesses recorded under the current profile, and a machine without a record must run setup first. For harnesses configured with `--use-session-credential`, sync resolves the session's API key again. If the key is unavailable, sync returns an error instead of creating a replacement. When nothing changes, sync exits with code 0 without modifying files, so you can run it on a schedule. Pass `--yes` to skip the prompt when sync finds changes. For Codex, sync restarts the background server. If the server has attached sessions, sync asks first unless you pass `--yes`. Restarting interrupts an in-progress turn but preserves thread history. If you decline the restart or it fails, the next sync tries again. ### Options **--dry-run** `BOOL` Preview the refresh without changing files or creating an API key. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--yes** `BOOL` Skip the interactive confirmation prompt. Required when stdin is not a terminal. **-v, --verbose** `BOOL` Enable verbose logging ### Examples Refresh every configured harness, as a scheduled run does: ```sh theme={"system"} baseten grid sync --yes ``` Preview what a sync would change: ```sh theme={"system"} baseten grid sync --dry-run ``` ### Filter output with `--jq` Print the configuration files a sync would change: ```sh theme={"system"} baseten grid sync --dry-run --jq '.items[] | select(.changed) | .config' ``` ### Output **Text mode (`--output text`):** The refreshed configuration of each harness, like setup. Use `--dry-run` to preview, and `--verbose` for per-harness details. **JSON mode (`--output json`):** Returns an `items` array with the sync result for each configured harness. ## status ```sh theme={"system"} baseten grid status [OPTIONS] ``` Show the installed versions, configuration path, and configured routes for each harness. A harness installed as both a CLI and a desktop app lists both versions, which share one configuration file. Without `--harness`, the command shows every harness configured at its default path. Status reads only local files, so it works after you uninstall the harness. It doesn't check the API key or live routes. Rerun setup to refresh routes. ### Options **--config-dir** `TEXT` Harness configuration directory. Requires exactly one `--harness`. Defaults to the harness's own location. **--harness** `TEXT (repeatable)` Harness to apply to. May be repeated. One of: `claude-code`, `codex`, `opencode`, `pi` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **-v, --verbose** `BOOL` Enable verbose logging ### Examples Inspect Codex configuration: ```sh theme={"system"} baseten grid status --harness codex ``` ### Filter output with `--jq` Print each harness's state: ```sh theme={"system"} baseten grid status --jq '.items[] | {harness, state}' ``` ### Output **Text mode (`--output text`):** Local configuration and configured routes. Use `--verbose` for setting names. **JSON mode (`--output json`):** Returns an `items` array with each harness's installation and configuration state. ## harness-defaults ```sh theme={"system"} baseten grid harness-defaults [OPTIONS] ``` Show the default routes for each harness. Use `--harness` to narrow the output; without it, the command shows every harness. Admins can change defaults on app.baseten.co or through the API. This command only reads them. ### Options **--harness** `TEXT (repeatable)` Harness to show. May be repeated. Defaults to every harness. One of: `claude-code`, `codex`, `opencode`, `pi` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID whose defaults to show. Defaults to your only team; required if you belong to more than one. Run 'baseten org team list' to see teams. **-v, --verbose** `BOOL` Enable verbose logging ### Examples Show every harness's defaults for your only team: ```sh theme={"system"} baseten grid harness-defaults ``` Show one team's defaults for one harness: ```sh theme={"system"} baseten grid harness-defaults --team Engineering --harness claude-code ``` ### Filter output with `--jq` Print the primary route for Claude Code: ```sh theme={"system"} baseten grid harness-defaults --harness claude-code --jq '.items[0].primary.route.name' ``` ### Output **Text mode (`--output text`):** Table with columns: HARNESS, PRIMARY, BACKGROUND. Each route is followed by its source in parentheses; '-' means no default is set. JSON includes the team and each default's full route and source. **JSON mode (`--output json`):** Returns the team and an `items` array of harness defaults, including each route and its source. ## teardown ```sh theme={"system"} baseten grid teardown [OPTIONS] ``` Remove the Baseten integration settings so the harness's own defaults apply. Teardown doesn't restore previous values, and it keeps unrelated settings. Without `--harness`, the command removes every integration configured at its default path. Teardown deletes a removed harness's Grid API key after no other harness on the machine uses it. It never deletes a key installed with `--use-session-credential`. Teardown also removes the setup record so `baseten grid sync` stops refreshing the harness. It works after you uninstall the harness. For Codex, teardown re-enables ChatGPT login and restarts the background server if it's running. When the server has attached Codex sessions, teardown asks for confirmation first. Run `codex login` to sign back in. ### Options **--config-dir** `TEXT` Harness configuration directory. Requires exactly one `--harness`. Defaults to the harness's own location. **--dry-run** `BOOL` Preview removal without changing files. **--harness** `TEXT (repeatable)` Harness to apply to. May be repeated. One of: `claude-code`, `codex`, `opencode`, `pi` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--yes** `BOOL` Skip the interactive confirmation prompt. Required when stdin is not a terminal. **-v, --verbose** `BOOL` Enable verbose logging ### Examples Preview removal: ```sh theme={"system"} baseten grid teardown --harness codex --dry-run ``` Remove integration settings without prompting: ```sh theme={"system"} baseten grid teardown --harness codex --yes ``` ### Filter output with `--jq` List the settings teardown would remove: ```sh theme={"system"} baseten grid 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`):** Returns an `items` array with the teardown result for each selected harness. ## route Manage routes. Baseten derives each route's name from its target. You can't change a route's name, team, or target type after creation, but you can update its classifier configuration. A model route sends every request to one Baseten Model API or external-provider connection. A classifier-backed route lets a managed classifier choose among the routes in `allowed_routes`; if the classifier selects none, Grid uses `default_route`. ### list ```sh theme={"system"} baseten grid route list [OPTIONS] ``` List all available routes across your accessible teams, newest first. In scripts that expect results from one team, always pass `--team`. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID to list routes of. Omit to list across all accessible teams. Run 'baseten org team list' to see teams. **-v, --verbose** `BOOL` Enable verbose logging #### Examples List routes across your teams: ```sh theme={"system"} baseten grid route list ``` List one team's routes: ```sh theme={"system"} baseten grid route list --team Engineering ``` #### Filter output with `--jq` Print route names: ```sh theme={"system"} baseten grid route list --jq '.items[].name' ``` #### Output **Text mode (`--output text`):** Table with columns: ID, TEAM ID, TEAM NAME, DISPLAY NAME, NAME, CREATED. Run `baseten grid route describe` to inspect a route's target. When no routes match, prints "No routes found." to stderr. **JSON mode (`--output json`):** Returns all matching routes in an `items` array. `target.type` is `BASETEN_MODEL_API`, `CONNECTION`, or `CLASSIFIER`. Model targets include `model`; connection targets also include `connection_id`. Classifier targets include `classifier`, `allowed_routes`, and `default_route`. ### describe ```sh theme={"system"} baseten grid route describe [OPTIONS] ``` Describe a route by ID or exact name. Pass exactly one of `--id` or `--name`. #### Options **--id** `TEXT` Stable route ID. Mutually exclusive with other flags in group `route-ref`. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--name** `TEXT` Exact route name, including its organization-owned prefix. Mutually exclusive with other flags in group `route-ref`. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **-v, --verbose** `BOOL` Enable verbose logging #### Examples Describe a route by name: ```sh theme={"system"} baseten grid route describe --name acme/assistant ``` #### Filter output with `--jq` Print the invoke URL: ```sh theme={"system"} baseten grid route describe --id --jq '.invoke_url' ``` #### Output **Text mode (`--output text`):** Field-per-line summary of the route, including its target, invoke URL, and team name. Classifier and referenced route names include IDs in parentheses. For an unrecognized target type, text mode prints `unrecognized type`. **JSON mode (`--output json`):** Returns the route and its target configuration. `target.type` is `BASETEN_MODEL_API`, `CONNECTION`, or `CLASSIFIER`. Model targets include `model`; connection targets also include `connection_id`. Classifier targets include `classifier`, `allowed_routes`, and `default_route`. ### create ```sh theme={"system"} baseten grid route create [OPTIONS] ``` Create a model route with `--target-type` and `--target-model`. To create a classifier route, pass `--target-type classifier`, `--classifier-id`, one or more `--allowed-route-id` values, and `--default-route-id`. Baseten derives the route's name from its target. Run `baseten model-api list` to find Model API names. If you belong to one team, `--team` is optional. If you belong to several, specify a team. External providers use a connection owned by the route's team. The connection holds the provider's API key; pass its ID with `--target-connection-id`. When you specify a team, the connection must belong to that team. Set optional metadata with `--display-name` and `--description`. #### Options **--allowed-route-id** `TEXT (repeatable)` ID of a route the classifier may select. Repeat for each allowed route. **--classifier-id** `TEXT` Classifier ID from grid classifier list. Requires allowed and default route IDs. **--default-route-id** `TEXT` ID of the allowed route used when the classifier picks none. **--description** `TEXT` Optional route description (up to 1000 characters). **--display-name** `TEXT` Display name (1 to 255 characters). Defaults to the route name. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--target-connection-id** `TEXT` ID of a connection in the route's team, whose provider serves the route. Required with `--target-type` connection. **--target-model** `TEXT` Model API name or external provider model name. Required for non-classifier targets. **--target-type** `TEXT` *required* Target type. One of: `baseten-model-api`, `connection`, `classifier` **--team** `TEXT` Team name or ID the route belongs to. Defaults to your only team; required when you belong to several. Run 'baseten org team list' to see teams. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Create a Model API route: ```sh theme={"system"} baseten grid route create --target-type baseten-model-api --target-model ``` Create an external provider route through a team connection: ```sh theme={"system"} baseten grid route create --target-type connection --target-model --target-connection-id ``` Create a classifier-backed route: ```sh theme={"system"} baseten grid route create --target-type classifier --classifier-id --allowed-route-id --default-route-id ``` #### Filter output with `--jq` Print the created route ID: ```sh theme={"system"} baseten grid route create --target-type baseten-model-api --target-model --jq '.id' ``` #### Output **Text mode (`--output text`):** On success, prints "Created route `name` (`id`)" to stderr; no stdout output. **JSON mode (`--output json`):** Returns the created route. `target.type` is `BASETEN_MODEL_API`, `CONNECTION`, or `CLASSIFIER`. Model targets include `model`; connection targets also include `connection_id`. Classifier targets include `classifier`, `allowed_routes`, and `default_route`. ### update ```sh theme={"system"} baseten grid route update [OPTIONS] ``` Update a route by ID or exact name. Pass exactly one of `--id` or `--name`. Pass `--display-name` or `--description`; the command leaves omitted fields unchanged. To replace a classifier configuration, supply `--classifier-id`, `--allowed-route-id`, and `--default-route-id` together. Pass `--description ''` to clear the description. You can't change the route's name, team, target type, or non-classifier target. #### Options **--allowed-route-id** `TEXT (repeatable)` ID of a route the classifier may select. Repeat for each allowed route. **--classifier-id** `TEXT` Classifier ID from grid classifier list. Requires allowed and default route IDs. **--default-route-id** `TEXT` ID of the allowed route used when the classifier picks none. **--description** `TEXT` New description (up to 1000 characters). Pass an empty string to clear it. **--display-name** `TEXT` New display name (1 to 255 characters). Omit to keep it unchanged. **--id** `TEXT` Stable route ID. Mutually exclusive with other flags in group `route-ref`. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--name** `TEXT` Exact route name, including its organization-owned prefix. Mutually exclusive with other flags in group `route-ref`. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **-v, --verbose** `BOOL` Enable verbose logging #### Examples Change a route's description: ```sh theme={"system"} baseten grid route update --name acme/assistant --description 'Team assistant' ``` #### Filter output with `--jq` Change the display name and print it: ```sh theme={"system"} baseten grid route update --id --display-name Assistant --jq '.display_name' ``` #### Output **Text mode (`--output text`):** On success, prints "Updated route `name` (`id`)" to stderr; no stdout output. **JSON mode (`--output json`):** Returns the updated route. `target.type` is `BASETEN_MODEL_API`, `CONNECTION`, or `CLASSIFIER`. Model targets include `model`; connection targets also include `connection_id`. Classifier targets include `classifier`, `allowed_routes`, and `default_route`. ### delete ```sh theme={"system"} baseten grid route delete [OPTIONS] ``` Delete a route by ID or exact name. Pass exactly one of `--id` or `--name`. The command prompts for confirmation. Pass `--yes` to skip the prompt. When stdin isn't a terminal, pass `--yes`. #### Options **--id** `TEXT` Stable route ID. Mutually exclusive with other flags in group `route-ref`. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--name** `TEXT` Exact route name, including its organization-owned prefix. Mutually exclusive with other flags in group `route-ref`. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--yes** `BOOL` Skip the interactive confirmation prompt. Required when stdin is not a terminal. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Delete a route without prompting: ```sh theme={"system"} baseten grid route delete --name acme/assistant --yes ``` #### Filter output with `--jq` Print the deleted route's ID: ```sh theme={"system"} baseten grid route delete --id --yes --jq '.id' ``` #### Output **Text mode (`--output text`):** On success, prints "Deleted route `name` (`id`)" to stderr; no stdout output. **JSON mode (`--output json`):** Returns the deleted route's ID and name. ### usage ```sh theme={"system"} baseten grid route usage [OPTIONS] ``` Show routes usage and estimated costs as daily UTC buckets, oldest first, broken down by the dimensions passed to `--group-by`. Defaults match the API: the previous UTC day through today, grouped by model. Organization admins see organization usage, team admins see teams they manage, and other members see usage from their own keys. `--team` narrows the scope. Grouping by router includes only routed usage; don't add these totals to totals from other groupings. Usage covers whole UTC days. The CLI rounds `--start` down to the start of its day and `--end` up to the end of its day. It fetches every bucket in the window, paging as needed, until it collects `--limit` buckets. Usage can lag by up to 15 minutes, and Baseten retains it for 92 days. Model API costs use your prices and include tool calls. OpenAI, Anthropic, and xAI costs estimate what those providers charge and aren't Baseten charges. The results exclude Vertex and OpenAI-compatible usage. Run `baseten grid user-settings describe` to compare this month's spend with your limit. For machine-readable streaming, prefer `--output jsonl` over `--output json`. #### Options **--end** `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. **--group-by** `TEXT (repeatable)` (default: model) Dimension to break usage down by. May be repeated. One of: `user`, `team`, `model`, `provider`, `router` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--limit** `INTEGER` Maximum number of daily buckets, paging as needed. 0 for no limit. **--model** `TEXT (repeatable)` Only return usage for these models. May be repeated. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--provider** `TEXT (repeatable)` Only return usage for these providers. May be repeated. One of: `baseten-model-api`, `openai`, `anthropic`, `xai`, `vertex`, `openai-compatible` **--since** `TEXT` Window from a relative time ago until now (e.g. '7d'). Mutually exclusive with `--start` and `--end`. **--start** `TEXT` Start of the range, inclusive, snapped down to its UTC day. ISO 8601, local when no timezone is given. Defaults to the day before `--end`. **--team** `TEXT` Team name or ID to filter usage by. Without it, returns your authorized usage across teams. **--user-id** `TEXT (repeatable)` Only return usage from Grid API keys created by these user IDs. May be repeated. 'baseten whoami' shows your own. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Show usage per model since yesterday: ```sh theme={"system"} baseten grid route usage ``` Show which users drove usage over the last 7 days (admins): ```sh theme={"system"} baseten grid route usage --since 7d --group-by user ``` Break routed usage down by team and router: ```sh theme={"system"} baseten grid route usage --group-by team,router ``` #### Filter output with `--jq` Stream each day's cost per model as a JSONL stream: ```sh theme={"system"} baseten grid route usage --output jsonl --jq '.results[] | {model, cost_usd}' ``` #### Output **Text mode (`--output text`):** Table with a DATE column, one column per `--group-by` dimension, then INPUT, CACHED, and OUTPUT token counts and COST, followed by an ALL totals row. A day with no usage renders as a single "(no usage)" row. A cost of "-" means some of that usage couldn't be priced. The window goes to stderr. When no day in the window has any usage, prints "No usage in the selected window." to stderr instead of a table. **JSON mode (`--output json`):** Returns one record per UTC day, including days without usage. Each record contains its date and per-dimension usage in `results`. Values in `cost_usd` are exact decimal strings. ## API keys Use [`baseten org api-key list --type grid`](https://docs.baseten.co/reference/cli/baseten/org#api-key) to list Grid API keys. To revoke a key, use [`baseten org api-key delete`](https://docs.baseten.co/reference/cli/baseten/org#api-key). [`baseten grid setup`](https://docs.baseten.co/reference/cli/baseten/grid#setup) creates the API key used by configured harnesses. ## classifier ### list ```sh theme={"system"} baseten grid classifier list [OPTIONS] ``` Classifiers are managed by Baseten. Use their IDs when creating or updating classifier-backed routes. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **-v, --verbose** `BOOL` Enable verbose logging #### Examples List available classifiers: ```sh theme={"system"} baseten grid classifier list ``` #### Filter output with `--jq` Print classifier IDs: ```sh theme={"system"} baseten grid classifier list --jq '.items[].id' ``` #### Output **Text mode (`--output text`):** Table with ID and NAME columns. Lists all pages; an empty catalog prints a message to stderr. **JSON mode (`--output json`):** Returns an `items` array of classifiers. ## connection A connection lets routes use an external provider without storing that provider's API key in each route. It points to an existing team secret. To rotate credentials for every route that uses a connection, update the connection to point to another secret; the routes don't change. ### list ```sh theme={"system"} baseten grid connection list [OPTIONS] ``` List connections across your teams; use `--team` to select one. In scripts that expect results from one team, always pass `--team`. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to list across all accessible teams. **-v, --verbose** `BOOL` Enable verbose logging #### Examples List connections across your teams: ```sh theme={"system"} baseten grid connection list ``` #### Filter output with `--jq` Print connection IDs: ```sh theme={"system"} baseten grid connection list --jq '.items[].id' ``` #### Output **Text mode (`--output text`):** Table with ID, TEAM ID, TEAM NAME, PROVIDER, and SECRET NAME columns. Lists all pages; secret values are never returned. **JSON mode (`--output json`):** Returns an `items` array of connections. ### create ```sh theme={"system"} baseten grid connection create [OPTIONS] ``` The secret must belong to the connection's team. Creating a connection requires team admin. If you belong to one team, `--team` is optional. If you belong to several, specify a team. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--provider** `TEXT` *required* Upstream provider. One of: `anthropic`, `openai`, `xai` **--secret-name** `TEXT` *required* Name of an existing secret in the connection's team. **--team** `TEXT` Team name or ID. Omit to use your only team; required when you belong to several. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Connect Anthropic using a team secret: ```sh theme={"system"} baseten grid connection create --provider anthropic --secret-name ``` #### Filter output with `--jq` Print the new connection ID: ```sh theme={"system"} baseten grid connection create --provider openai --secret-name --jq '.id' ``` #### Output **Text mode (`--output text`):** Confirmation on stderr; JSON contains the created connection. **JSON mode (`--output json`):** Returns the created connection. ### update ```sh theme={"system"} baseten grid connection update [OPTIONS] ``` Updating a connection requires team admin. The provider must match the existing connection. You can't change the provider or owning team. #### Options **--id** `TEXT` *required* Connection ID. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--provider** `TEXT` *required* Upstream provider. One of: `anthropic`, `openai`, `xai` **--secret-name** `TEXT` *required* Name of an existing secret in the connection's team. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Change the secret used by a connection: ```sh theme={"system"} baseten grid connection update --id --provider anthropic --secret-name ``` #### Filter output with `--jq` Print the updated secret metadata: ```sh theme={"system"} baseten grid connection update --id --provider anthropic --secret-name --jq '.config' ``` #### Output **Text mode (`--output text`):** Confirmation on stderr; JSON contains the updated connection. **JSON mode (`--output json`):** Returns the updated connection. ### delete ```sh theme={"system"} baseten grid connection delete [OPTIONS] ``` Requires team admin. Leaves the referenced secret in place. Pass `--yes` to skip confirmation. #### Options **--id** `TEXT` *required* Connection ID. **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--yes** `BOOL` Skip confirmation; required when stdin is not a terminal. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Delete a connection: ```sh theme={"system"} baseten grid connection delete --id --yes ``` #### Filter output with `--jq` Print the deleted ID: ```sh theme={"system"} baseten grid connection delete --id --yes --jq '.id' ``` #### Output **Text mode (`--output text`):** Confirmation on stderr; JSON contains the deleted connection ID. **JSON mode (`--output json`):** Returns the deleted connection's ID. ## team-settings Team settings hold a team's Grid spend limits. Read them and change the limits that apply to the team. ### describe ```sh theme={"system"} baseten grid team-settings describe [OPTIONS] ``` If you belong to one team, `--team` is optional. If you belong to several, specify a team. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to use your only team; required when you belong to several. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Show your only team's settings: ```sh theme={"system"} baseten grid team-settings describe ``` #### Filter output with `--jq` Print the harness defaults: ```sh theme={"system"} baseten grid team-settings describe --jq '.harness_defaults' ``` #### Output **Text mode (`--output text`):** Team ID and name, monthly spend limits, and a table of harness default routes and their sources. **JSON mode (`--output json`):** Returns the team's Grid settings. ### update ```sh theme={"system"} baseten grid team-settings update [OPTIONS] ``` Only the fields you provide change. To configure a harness route, combine `--harness` with `--primary-route-id` or `--background-route-id`. Pass `null` to clear that route. `--clear-harness-defaults` clears the configured defaults for every harness. Spend limits are exact dollar amounts. The per-member limit applies to members who don't have an individual limit. The team-wide limit covers all members' combined Grid spend; when the team reaches it, Baseten rejects every member's Grid requests in that team. Pass `null` to remove one limit, or use `--clear-spend-limit` to remove both. Updating settings requires team admin. Changing the team-wide limit requires organization admin. If you belong to one team, `--team` is optional. If you belong to several, specify a team. #### Options **--background-route-id** `TEXT | null` Background route ID for Claude Code or OpenCode; null clears it. Requires `--harness`. **--clear-harness-defaults** `BOOL` Clear all configured harness defaults. Cannot be combined with `--harness` or route flags. **--clear-spend-limit** `BOOL` Clear both team spend limits. Requires organization admin. Cannot be combined with `--per-member-monthly-limit-usd` or `--team-wide-monthly-limit-usd`. **--harness** `TEXT` Harness whose default route IDs to update. One of: `claude-code`, `codex`, `opencode`, `pi` **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--per-member-monthly-limit-usd** `TEXT | null` Default monthly USD limit per member; null removes it. **--primary-route-id** `TEXT | null` Primary route ID; null clears the configured default. Requires `--harness`. **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to use your only team; required when you belong to several. **--team-wide-monthly-limit-usd** `TEXT | null` Team-wide monthly USD limit; null removes it. Requires organization admin. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Set the default monthly limit per member: ```sh theme={"system"} baseten grid team-settings update --per-member-monthly-limit-usd 100 ``` Set Codex's primary route: ```sh theme={"system"} baseten grid team-settings update --harness codex --primary-route-id ``` #### Filter output with `--jq` Clear and print the team-wide limit: ```sh theme={"system"} baseten grid team-settings update --team-wide-monthly-limit-usd null --jq '.spend_limit' ``` #### Output **Text mode (`--output text`):** The updated team settings, in the same format as describe. **JSON mode (`--output json`):** Returns the updated team settings. ## user-settings User settings hold individual members' Grid spend limits. Read them and change the limits that apply to one member. ### list ```sh theme={"system"} baseten grid user-settings list [OPTIONS] ``` List members across teams you administer. Use `--team` to select one team. In scripts that expect results from one team, always pass `--team`. This command requires team admin or organization admin. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to list across all accessible teams. **-v, --verbose** `BOOL` Enable verbose logging #### Examples List members' settings in a team: ```sh theme={"system"} baseten grid user-settings list --team ``` #### Filter output with `--jq` Print each member's limits: ```sh theme={"system"} baseten grid user-settings list --jq '.items[].spend_limit' ``` #### Output **Text mode (`--output text`):** Table with USER, EMAIL, TEAM ID, TEAM NAME, MONTH SPEND, EFFECTIVE LIMIT, and BLOCKED BY columns. Lists all pages; empty results print a message to stderr. **JSON mode (`--output json`):** Returns an `items` array of member settings. ### describe ```sh theme={"system"} baseten grid user-settings describe [OPTIONS] ``` By default, this command shows your settings (`--user-id me`). Reading another user's settings requires team admin or organization admin. If you belong to one team, `--team` is optional. If you belong to several, specify a team. The current-month override takes precedence over the member's standing limit. Without either, the team's per-member limit applies. The team-wide limit is independent: when the team reaches it, Baseten blocks every member even if they haven't reached their individual effective limit. `blocked_by` reports `member` or `team` so you can tell which limit stopped requests. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to use your only team; required when you belong to several. **--user-id** `TEXT` (default: me) User ID, or me for yourself. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Show your own settings: ```sh theme={"system"} baseten grid user-settings describe ``` #### Filter output with `--jq` Print your effective monthly limit: ```sh theme={"system"} baseten grid user-settings describe --jq '.spend_limit.effective' ``` #### Output **Text mode (`--output text`):** User and team identifiers, monthly spend, standing and override limits, effective limit, and blocked status. **JSON mode (`--output json`):** Returns the member's Grid settings. ### update ```sh theme={"system"} baseten grid user-settings update [OPTIONS] ``` By default, this command updates your settings (`--user-id me`). Updating any member's limits, including your own, requires team admin or organization admin. Only the limits you provide change. Pass `null` to clear a limit, and provide dollar amounts as exact decimal values. A current-month override supersedes the standing limit until the UTC month ends or you clear the override. If you belong to one team, `--team` is optional. If you belong to several, specify a team. #### Options **-q, --jq** `TEXT` Filter JSON output with a jq expression; implies `--output` json (or jsonl for streamed commands) **--month-override-usd** `TEXT | null` USD limit for the current UTC month; null removes the override. **-o, --output** `TEXT` (default: text) Output format One of: `text`, `json`, `jsonl`, `none` **--profile** `TEXT` Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile **--team** `TEXT` Team name or ID. Omit to use your only team; required when you belong to several. **--user-id** `TEXT` (default: me) User ID, or me for yourself. **--user-monthly-limit-usd** `TEXT | null` Standing monthly USD limit for this user in the team; null removes it. **-v, --verbose** `BOOL` Enable verbose logging #### Examples Set a member's standing monthly limit: ```sh theme={"system"} baseten grid user-settings update --team --user-id --user-monthly-limit-usd 100 ``` #### Filter output with `--jq` Clear and print your current-month override: ```sh theme={"system"} baseten grid user-settings update --month-override-usd null --jq '.spend_limit' ``` #### Output **Text mode (`--output text`):** The updated user settings, in the same format as describe. **JSON mode (`--output json`):** Returns the updated member settings. ## Commands moved from earlier releases The former `baseten harness` and `baseten route` commands now run under `baseten grid`: | CLI 1.4 | CLI 1.5 | | - | - | | `baseten harness ` | `baseten grid ` | | `baseten route ` | `baseten grid route ` | | `baseten route api-key list` | `baseten org api-key list --type grid` | | `baseten route api-key delete --prefix ` | `baseten org api-key delete --prefix ` | Route-selection flags now take route IDs and end in `-id`, such as `--primary-route-id`, `--background-route-id`, and `--target-connection-id`. The API-key delete command removes one key at a time by name or prefix; the former `--all` option has no replacement. Route JSON also represents external providers with a `CONNECTION` target and `connection_id` instead of provider-specific target types. Update scripts that parse these fields.