Skip to main content
Configure harness integrations and manage routes with Baseten Grid.
Grid commands are in pre-release and support macOS and Linux. Their arguments, flags, and output can change.

setup

Configure installed harnesses with your team’s routes and Grid credentials. If you omit --harness, setup lets you select from the harnesses installed on your machine. Repeat --harness to configure several. The claude harness configures Claude Code and, when the app is installed, Claude Desktop. Setup replaces each harness’s model picker with your team’s routes and their model metadata. Claude Code and Claude Desktop list 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. Claude Code, Claude Desktop, Codex, and Pi get a short-lived Grid token from the CLI when they need one. Each token is scoped to you and the team and lasts four hours. For OpenCode, the first setup creates a Grid API key, and later runs reuse it. With --use-session-credential, or when the CLI uses BASETEN_API_KEY, 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. For Claude Desktop, setup adds a configuration to the app’s third-party configuration library and switches the app to third-party mode. Quit and reopen the app to load it. When the team has intelligent routes, setup adds a served-model indicator that shows which model served each response: a status line in Claude Code, or a Stop hook if you already have a status line, an extension in Pi, and a plugin in OpenCode 2. Interactive setup asks first. Pass --hide-served-model-indicator to leave it out and remove one that setup added before. To turn it off without rerunning setup, set BASETEN_CLAUDE_SERVED_MODEL, BASETEN_PI_SERVED_MODEL, or BASETEN_OPENCODE_SERVED_MODEL to 0. Pass --git-context to have Claude Code, OpenCode, and Pi add the git origin URL, branch, and commit to the session context when a session starts inside a git repository. Baseten uses this context to train its router. Setup without the flag removes the context hook, plugin, or extension it added before.

Options

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.
TEXT
Harness configuration directory. Requires exactly one --harness. Defaults to the harness’s own location.
BOOL
Preview the configuration without changing files or creating an API key.
TEXT
Route ID to fall back to when the default is unavailable (Claude Code). Defaults to the primary route.
BOOL
Add the git origin URL, branch, and commit to each Claude Code, OpenCode, and Pi session’s context, through a SessionStart hook, plugin, or extension. Without it, setup removes them if it added them before.
TEXT (repeatable)
Harness to apply to. May be repeated.One of: claude, codex, opencode, pi
BOOL
Hide which model served each response on intelligent routes in the selected harnesses (a status line or Stop hook in Claude Code, an extension in Pi, a plugin in OpenCode 2), and remove it if setup added it before. When omitted, setup shows it, asking first when interactive.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
Name of the Grid API key, if setup creates one. Defaults to baseten-harness-hostname-random suffix.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Primary route ID. Defaults to the team’s default for the harness, else the first route the harness lists.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Route ID for subagents (Claude Code and OpenCode). Defaults to the harness’s own setting.
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.
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.
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Configure installed harnesses interactively:
Install a pre-minted key from the environment instead of creating one:
Preview configuration for one harness:
Apply a configuration without prompting:

Filter output with --jq

Print the configuration file paths:

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

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. Pass --hide-served-model-indicator or --git-context to change the recorded choice for every synced harness. Without them, sync keeps the recorded choices. 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

BOOL
Preview the refresh without changing files or creating an API key.
BOOL
Add the git origin URL, branch, and commit to each Claude Code, OpenCode, and Pi session’s context, through a SessionStart hook, plugin, or extension. Records the choice; =false removes them.
BOOL
Hide which model served each response on intelligent routes in the synced harnesses (a status line or Stop hook in Claude Code, an extension in Pi, a plugin in OpenCode 2), and remove it if setup added it before. Records the choice; when omitted, sync keeps the recorded one.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Refresh every configured harness, as a scheduled run does:
Preview what a sync would change:

Filter output with --jq

Print the configuration files a sync would change:

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

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

TEXT
Harness configuration directory. Requires exactly one --harness. Defaults to the harness’s own location.
TEXT (repeatable)
Harness to apply to. May be repeated.One of: claude, codex, opencode, pi
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Inspect Codex configuration:

Filter output with --jq

Print each harness’s 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.

teardown

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 removes the served-model indicator and git context hook, plugin, or extension that setup added. 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. For Claude Desktop, teardown switches the app back to its own sign-in and removes Baseten’s configuration from the app’s library.

Options

TEXT
Harness configuration directory. Requires exactly one --harness. Defaults to the harness’s own location.
BOOL
Preview removal without changing files.
TEXT (repeatable)
Harness to apply to. May be repeated.One of: claude, codex, opencode, pi
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Preview removal:
Remove integration settings without prompting:

Filter output with --jq

List the settings teardown would remove:

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 after creation. A model route sends every request to one Baseten Model API or external-provider connection. An intelligent route uses a Baseten-managed route classifier to pick the model for each request, weighing cost against quality according to the route’s trade-off.

list

List all available routes across your accessible teams, newest first. In scripts that expect results from one team, always pass --team.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID to list routes of. Omit to list across all accessible teams. Run ‘baseten org team list’ to see teams.
BOOL
Enable verbose logging

Examples

List routes across your teams:
List one team’s routes:

Filter output with --jq

Print route names:

Output

Text mode (--output text): Table with columns: ID, TEAM, 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 INTELLIGENT. Model targets include model; connection targets also include connection_id. Intelligent targets include route_classifier and tradeoff.

describe

Describe a route by ID or exact name. Pass exactly one of --id or --name.

Options

TEXT
Stable route ID.Mutually exclusive with other flags in group route-ref.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
Exact route name, including its organization-owned prefix.Mutually exclusive with other flags in group route-ref.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Describe a route by name:

Filter output with --jq

Print the invoke URL:

Output

Text mode (--output text): Field-per-line summary of the route, including its target, invoke URL, and team name. Route classifier 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 INTELLIGENT. Model targets include model; connection targets also include connection_id. Intelligent targets include route_classifier and tradeoff.

create

Create a model route with --target-type and --target-model. To create an intelligent route, pass --target-type intelligent with --route-classifier-id and --tradeoff (cost, balanced, or intelligence) instead of a model. Baseten derives the route’s name from its target. Run baseten model-api list to find Model API names, and baseten grid route-classifier list to find route classifier IDs. 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

TEXT
Optional route description (up to 1000 characters).
TEXT
Display name (1 to 255 characters). Defaults to the route name.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
ID of the route classifier that picks the model per request. Required with --target-type intelligent. List them with ‘baseten grid route-classifier list’.
TEXT
ID of a connection in the route’s team, whose provider serves the route. Required with --target-type connection.
TEXT
Model API name or external provider model name. Required with --target-type baseten-model-api or connection.
TEXT
required
Target type.One of: baseten-model-api, connection, intelligent
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.
TEXT
How the route classifier weighs cost against quality. Required with --target-type intelligent.One of: cost, balanced, intelligence
BOOL
Enable verbose logging

Examples

Create a Model API route:
Create an external provider route through a team connection:
Create an intelligent route:

Filter output with --jq

Print the created route 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 INTELLIGENT. Model targets include model; connection targets also include connection_id. Intelligent targets include route_classifier and tradeoff.

update

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. Pass --description '' to clear the description. You can’t change the route’s name, team, or target.

Options

TEXT
New description (up to 1000 characters). Pass an empty string to clear it.
TEXT
New display name (1 to 255 characters). Omit to keep it unchanged.
TEXT
Stable route ID.Mutually exclusive with other flags in group route-ref.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
Exact route name, including its organization-owned prefix.Mutually exclusive with other flags in group route-ref.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Change a route’s description:

Filter output with --jq

Change the display name and print it:

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 INTELLIGENT. Model targets include model; connection targets also include connection_id. Intelligent targets include route_classifier and tradeoff.

delete

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

TEXT
Stable route ID.Mutually exclusive with other flags in group route-ref.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
Exact route name, including its organization-owned prefix.Mutually exclusive with other flags in group route-ref.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Delete a route without prompting:

Filter output with --jq

Print the deleted route’s 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

Show routes usage and estimated costs over a window of UTC days, broken down by the dimensions passed to --group-by. By default, it covers 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 intelligent route counts only usage sent through intelligent routes. Grouping by harness includes an Unknown group for usage with no recorded harness. 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. Text output ends with your spend this month against your team limit. Pass --team if you belong to several teams. For machine-readable streaming, prefer --output jsonl over --output json.

Options

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.
TEXT (repeatable)
default:"model"
Dimension to break usage down by. May be repeated.One of: user, team, model, provider, intelligent-route, harness
TEXT (repeatable)
Only return usage for these harnesses. May be repeated. Omit to include usage with no recorded harness.One of: claude-code, codex, opencode, pi
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
INTEGER
Maximum number of daily buckets, paging as needed. 0 for no limit.
TEXT (repeatable)
Only return usage for these models. May be repeated.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT (repeatable)
Only return usage for these providers. May be repeated.One of: baseten-model-api, openai, anthropic, xai, vertex, openai-compatible
TEXT
Window from a relative time ago until now (e.g. ‘7d’). Mutually exclusive with --start and --end.
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.
TEXT
Team name or ID to filter usage by. Without it, returns your authorized usage across teams.
TEXT (repeatable)
Only return usage from Grid API keys created by these user IDs. May be repeated. ‘baseten whoami’ shows your own.
BOOL
Enable verbose logging

Examples

Show usage per model since yesterday:
Show which users drove usage over the last 7 days (admins):
Break intelligent route usage down by team and intelligent route:
Show usage by coding agent over the last 7 days:
Compare Codex and Claude Code usage:

Filter output with --jq

Stream each day’s cost per model as a JSONL stream:

Output

Text mode (--output text): The total cost, a chart of cost per day for each --group-by value (in a terminal, for windows longer than a day), then one line per value with its cost and share, most expensive first. Values past the top five are summed into “other”. The output ends with your spend this month in the team against your limit. A cost of ”-” means some of that usage couldn’t be priced. The window goes to stderr, as does “No usage in the selected window.” when there’s no usage. Use --output json for token counts and per-day detail. 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

baseten org api-key list includes Grid API keys; pass --type grid to list only Grid keys. To revoke a key, use baseten org api-key delete. To create a personal Grid key, whose usage counts against your Grid budget in the team, run baseten org api-key create --type grid with --team and --name. baseten grid setup creates a key only for OpenCode. For keys owned by a bot or scheduled job, see machine-user.

route-classifier

Baseten manages route classifiers. An intelligent route uses one to pick the model for each request.

list

List the available route classifiers.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

List available route classifiers:

Filter output with --jq

Print route classifier IDs:

Output

Text mode (--output text): Table with ID, NAME, TRADEOFFS, and DECIDABLE MODELS columns. TRADEOFFS is “all” when the route classifier supports every trade-off. Lists all pages; an empty catalog prints a message to stderr. JSON mode (--output json): Returns an items array of route classifiers.

describe

Show a route classifier by ID.

Options

TEXT
required
Route classifier ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Describe a route classifier:

Filter output with --jq

Print the models the route classifier picks from:

Output

Text mode (--output text): Field-per-line summary with the route classifier’s ID, name, supported trade-offs, and decidable models. Trade-offs is “all” when the route classifier supports every trade-off. JSON mode (--output json): Returns the route classifier.

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

List connections across your teams; use --team to select one. In scripts that expect results from one team, always pass --team.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to list across all accessible teams.
BOOL
Enable verbose logging

Examples

List connections across your teams:

Filter output with --jq

Print connection IDs:

Output

Text mode (--output text): Table with ID, TEAM, PROVIDER, and SECRET NAME columns. Lists all pages; secret values are never returned. JSON mode (--output json): Returns an items array of connections.

describe

Show a connection by ID. Secret values are never returned.

Options

TEXT
required
Connection ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Describe a connection:

Filter output with --jq

Print the connection’s team:

Output

Text mode (--output text): Field-per-line summary with the connection’s ID, team, provider, secret name, and timestamps. JSON mode (--output json): Returns the connection, without secret values.

create

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

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
required
Upstream provider.One of: anthropic, openai, xai
TEXT
required
Name of an existing secret in the connection’s team.
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
BOOL
Enable verbose logging

Examples

Connect Anthropic using a team secret:

Filter output with --jq

Print the new connection ID:

Output

Text mode (--output text): Confirmation on stderr; JSON contains the created connection. JSON mode (--output json): Returns the created connection.

update

Updating a connection requires team admin. The provider must match the existing connection. You can’t change the provider or owning team.

Options

TEXT
required
Connection ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
required
Upstream provider.One of: anthropic, openai, xai
TEXT
required
Name of an existing secret in the connection’s team.
BOOL
Enable verbose logging

Examples

Change the secret used by a connection:

Filter output with --jq

Print the updated secret metadata:

Output

Text mode (--output text): Confirmation on stderr; JSON contains the updated connection. JSON mode (--output json): Returns the updated connection.

delete

Requires team admin. Leaves the referenced secret in place. Pass --yes to skip confirmation.

Options

TEXT
required
Connection ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Skip confirmation; required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Delete a connection:

Filter output with --jq

Print the deleted 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

If you belong to one team, --team is optional. If you belong to several, specify a team.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
BOOL
Enable verbose logging

Examples

Show your only team’s settings:

Filter output with --jq

Print the harness defaults:

Output

Text mode (--output text): Team 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

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

TEXT | null
Background route ID for Claude Code or OpenCode; null clears it. Requires --harness.
BOOL
Clear all configured harness defaults. Cannot be combined with --harness or route flags.
BOOL
Clear both team spend limits. Requires organization admin. Cannot be combined with --per-member-monthly-limit-usd or --team-wide-monthly-limit-usd.
TEXT
Harness whose default route IDs to update.One of: claude, codex, opencode, pi
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT | null
Default monthly USD limit per member; null removes it.
TEXT | null
Primary route ID; null clears the configured default. Requires --harness.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
TEXT | null
Team-wide monthly USD limit; null removes it. Requires organization admin.
BOOL
Enable verbose logging

Examples

Set the default monthly limit per member:
Set Codex’s primary route:

Filter output with --jq

Clear and print the team-wide 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

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

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to list across all accessible teams.
BOOL
Enable verbose logging

Examples

List members’ settings in a team:

Filter output with --jq

Print each member’s limits:

Output

Text mode (--output text): Table with USER, EMAIL, TEAM, 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

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

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
TEXT
default:"me"
User ID, or me for yourself.
BOOL
Enable verbose logging

Examples

Show your own settings:

Filter output with --jq

Print your effective monthly limit:

Output

Text mode (--output text): User ID, team name, monthly spend, standing and override limits, effective limit, and blocked status. JSON mode (--output json): Returns the member’s Grid settings.

update

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

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT | null
USD limit for the current UTC month; null removes the override.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
TEXT
default:"me"
User ID, or me for yourself.
TEXT | null
Standing monthly USD limit for this user in the team; null removes it.
BOOL
Enable verbose logging

Examples

Set a member’s standing monthly limit:

Filter output with --jq

Clear and print your current-month override:

Output

Text mode (--output text): The updated user settings, in the same format as describe. JSON mode (--output json): Returns the updated member settings.

machine-user

A machine user is a team-owned identity, such as a bot or a scheduled job, with its own Grid budget and API keys. Managing machine users requires team admin.

list

Lists machine users across the teams you administer; use --team to select one.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to list across all accessible teams.
BOOL
Enable verbose logging

Examples

List machine users in a team:

Filter output with --jq

Print machine user IDs:

Output

Text mode (--output text): Table with ID, NAME, TEAM, and CREATED columns. Lists all pages; empty results print a message to stderr. JSON mode (--output json): Returns an items array of machine users.

create

Set a machine user’s spend limit with baseten grid user-settings update --team <team> --user-id <machine-user-id>; without one, it uses the team’s per-member default. Creates the machine user with one API key, printed exactly once; pass --no-api-key to create it without one. --api-key-name defaults to a name derived from the machine user’s. Key names are lowercase letters, numbers, and hyphens, unique among the machine user’s keys. Omit --team to let the API select your only team; specify a team when you belong to several.

Options

TEXT
Name of the first API key. Cannot be combined with --no-api-key.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Name of the machine user, unique within the team.
BOOL
Create the machine user without an API key.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
TEXT
Team name or ID. Omit to use your only team; required when you belong to several.
BOOL
Enable verbose logging

Examples

Create a machine user for a review bot:

Filter output with --jq

Print the new machine user’s ID and its one-time key:

Output

Text mode (--output text): Prints the raw API key value on stdout (one line), and the machine user’s ID plus “Save this key now. It will not be shown again.” on stderr. With --no-api-key, only the stderr line. JSON mode (--output json): Returns the machine user and, unless you pass --no-api-key, its one-time api_key.

describe

Shows a machine user’s name, team, and creator. Requires team admin.

Options

TEXT
required
Machine user ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Show a machine user:

Filter output with --jq

Print the machine user’s team ID:

Output

Text mode (--output text): ID, name, team, creator, and creation time. JSON mode (--output json): Returns the machine user.

update

Requires team admin. Names are unique within the team.

Options

TEXT
required
Machine user ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
New name for the machine user, unique within the team.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Rename a machine user:

Filter output with --jq

Print the new name:

Output

Text mode (--output text): The updated machine user, in the same format as describe. JSON mode (--output json): Returns the machine user.

delete

Requires team admin. Its API keys stop working; its usage history remains. Pass --yes to skip confirmation.

Options

TEXT
required
Machine user ID.
TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Skip confirmation; required when stdin is not a terminal.
BOOL
Enable verbose logging

Examples

Delete a machine user:

Filter output with --jq

Print the deleted ID:

Output

Text mode (--output text): Prints a confirmation to stderr. JSON mode (--output json): Returns the deleted machine user’s ID.

machine-user api-key

list

Lists key metadata; key values are never returned. Requires team admin.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Machine user ID.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

List a machine user’s keys:

Filter output with --jq

Print the key prefixes:

Output

Text mode (--output text): Table with columns: NAME, KEY (prefix + ****), TYPE, TEAM, CREATED, LAST USED, EXPIRES, as in baseten org api-key list. When the machine user has no keys, prints “No API keys found.” to stderr. JSON mode (--output json): Returns a keys array of key metadata.

create

The key value is printed to stdout exactly once and cannot be retrieved later. --name defaults to a name derived from the machine user’s. Key names are lowercase letters, numbers, and hyphens, unique among the machine user’s keys. Requires team admin.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Machine user ID.
TEXT
Name of the API key.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Create a named key for a machine user:

Filter output with --jq

Print just the raw key value:

Output

Text mode (--output text): Prints the raw API key value on stdout (one line). Also prints “Save this key now. It will not be shown again.” to stderr. JSON mode (--output json): Returns the new key, including its one-time api_key value.

delete

Deletes one key; the machine user and its other keys are unchanged. Exactly one of --name or --prefix is required. Requires team admin.

Options

TEXT
Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
TEXT
required
Machine user ID.
TEXT
Name of the API key to delete.Mutually exclusive with other flags in group identifier.
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
TEXT
Prefix of the API key to delete (as shown in list).Mutually exclusive with other flags in group identifier.
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
BOOL
Enable verbose logging

Examples

Delete a key by name:

Filter output with --jq

Print the deleted key’s prefix:

Output

Text mode (--output text): Prints Deleted API key <prefix> to stderr on success; no stdout output. JSON mode (--output json): Returns the deleted key’s prefix.

Commands moved from earlier releases

The former baseten harness and baseten route commands now run under baseten grid: baseten grid harness-defaults was removed in CLI 1.7. To see a team’s harness defaults, run baseten grid team-settings describe. 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.