> ## 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 CLI overview

> Manage your Baseten workspace from the command line: organizations, API keys, secrets, deployment lifecycle, replicas, and raw API access. Designed for automation.

The Baseten CLI manages your Baseten workspace from the command line: models, deployments, environments, secrets, API keys, and raw API access. Every Baseten-native command supports `--output json` and `--jq` filtering, so anything you do interactively is scriptable.

The CLI is open source on [GitHub](https://github.com/basetenlabs/baseten-cli), where you can browse the code, watch for new releases, and file issues.

The `baseten train` and `baseten loops` command trees cover most Training and Loops work, and delegate to truss for the commands that need a Python config file. For authoring Chains, or when you want the truss commands directly, use `baseten truss` or the [Truss CLI](/reference/cli/truss/overview). The [CLI overview](/reference/cli/index) explains when to reach for each.

For a task-oriented guide to the deployment commands (scale, pause, promote, clean up, logs), see [Manage deployments](/deployment/manage/overview).

## Install

Install with Homebrew on macOS or Linux:

```sh theme={"system"}
brew tap basetenlabs/baseten
brew trust --formula basetenlabs/baseten/baseten
brew install baseten
```

Upgrade later with `brew update && brew upgrade baseten`. See
[tap trust](https://docs.brew.sh/Tap-Trust) in the Homebrew docs.

<Accordion title="Manual install (Windows, or a specific version)">
  Download and extract the `baseten` binary for your platform, then place it on your `PATH`.

  <Tabs>
    <Tab title="macOS (arm64)">
      Download and extract `baseten` into `/usr/local/bin`:

      ```sh theme={"system"}
      curl -sL https://github.com/basetenlabs/baseten-cli/releases/download/v1.3.0/baseten_1.3.0_darwin_arm64.tar.gz \
        | sudo tar xz -C /usr/local/bin baseten
      ```
    </Tab>

    <Tab title="Linux (x64)">
      Download and extract `baseten` into `/usr/local/bin`:

      ```sh theme={"system"}
      curl -sL https://github.com/basetenlabs/baseten-cli/releases/download/v1.3.0/baseten_1.3.0_linux_amd64.tar.gz \
        | sudo tar xz -C /usr/local/bin baseten
      ```
    </Tab>

    <Tab title="Windows (x64)">
      Download and extract the archive, then move `baseten.exe` to a directory on your `PATH`:

      ```powershell theme={"system"}
      Invoke-WebRequest `
        https://github.com/basetenlabs/baseten-cli/releases/download/v1.3.0/baseten_1.3.0_windows_amd64.zip `
        -OutFile baseten.zip; Expand-Archive -Force baseten.zip .
      ```
    </Tab>
  </Tabs>

  For other platforms or a specific version, download an archive from [GitHub releases](https://github.com/basetenlabs/baseten-cli/releases) and move `baseten` onto your `PATH`.
</Accordion>

Verify the install:

```sh theme={"system"}
baseten version
```

## Authenticate

Log in interactively:

```sh theme={"system"}
baseten auth login
```

For automation, set `BASETEN_API_KEY` in the environment instead. See [`baseten auth`](/reference/cli/baseten/auth) for browser login, reading a key from stdin, switching accounts, and credential storage.

## Output and filtering

Every Baseten-native command supports four output formats through `--output`:

* `text` (default): human-readable narrative.
* `json`: a single JSON document. Pair with `--jq EXPR` to extract one field.
* `jsonl`: one JSON record per line. Used by commands that stream results.
* `none`: suppress stdout entirely.

```sh theme={"system"}
baseten model push --jq '.predict_url'
```

`--jq` implies `--output json` (or `jsonl` for streamed commands), so a single flag turns any command into a clean value for the next stage of your pipeline.

## Global flags

These flags work on every Baseten-native command:

| Flag | Description |
| - | - |
| `--profile` | Use a specific stored profile for this command, overriding `BASETEN_PROFILE` and the current profile. |
| `--output`, `-o` | Output format: `text`, `json`, `jsonl`, or `none`. See [Output and filtering](#output-and-filtering). |
| `--jq`, `-q` | Filter JSON output with a jq expression. See [Output and filtering](#output-and-filtering). |
| `--verbose`, `-v` | Enable verbose logging. |

## Command groups

The `baseten` CLI organizes commands by resource:

```
baseten [OPTIONS] COMMAND [SUBCOMMAND] [ARGS]...
```

Start from the resource you need to manage.

| Command group | Use it to |
| - | - |
| [`baseten api`](/reference/cli/baseten/api) | Make raw management or inference API requests. |
| [`baseten auth`](/reference/cli/baseten/auth) | Log in, log out, switch accounts, and inspect the active account. |
| [`baseten harness`](/reference/cli/baseten/harness) | Configure Claude Code, Codex, OpenCode, and Pi to use Baseten routes, and report your routes usage. Pre-release. |
| [`baseten model`](/reference/cli/baseten/model) | Push, watch, list, describe, predict against, rename, delete, and fetch audit logs for models. |
| [`baseten model deployment`](/reference/cli/baseten/model-deployment) | Activate, configure, download, promote, delete, describe, list, stream logs from, fetch metrics for, rename, and update autoscaling and request backpressure on deployments. |
| [`baseten model deployment replica`](/reference/cli/baseten/model-deployment-replica) | Terminate an individual deployment replica. |
| [`baseten model environment`](/reference/cli/baseten/model-environment) | Activate, deactivate, describe, list, stream logs from, fetch metrics for, and update autoscaling, promotion, and request backpressure on model environments. |
| [`baseten model environment autoscaling-schedule`](/reference/cli/baseten/model-environment-autoscaling-schedule) | Create, list, update, delete, and configure autoscaling schedules for an environment. |
| [`baseten model image`](/reference/cli/baseten/model-image) | Build a local Docker image or write out a build context from a model directory. |
| [`baseten model-api`](/reference/cli/baseten/model-api) | List, inspect, predict against, and report token usage for Baseten Model APIs. |
| [`baseten org api-key`](/reference/cli/baseten/org-api-key) | List, create, and delete organization API keys. |
| [`baseten org billing`](/reference/cli/baseten/org-billing) | Inspect organization billing usage. |
| [`baseten org secret`](/reference/cli/baseten/org-secret) | List, set, and delete organization secrets. |
| [`baseten org team`](/reference/cli/baseten/org-team) | List and describe organization teams. |
| [`baseten org user`](/reference/cli/baseten/org-user) | List and describe organization users. |
| [`baseten org audit-logs`](/reference/cli/baseten/org) | List workspace audit-log entries. |
| [`baseten org describe`](/reference/cli/baseten/org) | Describe the caller's organization. |
| [`baseten org regions`](/reference/cli/baseten/org) | List the regions the organization can deploy models in. |
| [`baseten route`](/reference/cli/baseten/route) | List, describe, create, update, and delete routes, and report routes usage and costs. Pre-release. |
| [`baseten route api-key`](/reference/cli/baseten/route-api-key) | List and delete the routes API keys you created. Pre-release. |
| [`baseten sandbox`](/reference/cli/baseten/sandbox) | Create, list, describe, update, delete, and run commands in sandboxes. Pre-release. |
| [`baseten sandbox image`](/reference/cli/baseten/sandbox-image) | Push, list, describe, delete, and inspect build logs for sandbox images. Pre-release. |
| [`baseten sandbox process`](/reference/cli/baseten/sandbox-process) | Start, list, describe, stream logs from, wait for, stop, and kill processes in a sandbox. Pre-release. |
| [`baseten ssh`](/reference/cli/baseten/ssh) | Set up SSH access to running Baseten workloads. |
| [`baseten volume`](/reference/cli/baseten/volume) | Store file trees once and mount them into models, training jobs, and Loops. Pre-release. |
| [`baseten volume sync`](/reference/cli/baseten/volume-sync) | Start, describe, list, and cancel jobs that copy a remote source into a volume. Pre-release. |
| [`baseten train`](/reference/cli/baseten/train) | Initialize, push, list, describe, log, metric, stop, recreate, update, and download training jobs, and manage projects, capacity, checkpoints, and workstations. |
| [`baseten loops`](/reference/cli/baseten/loops) | Run Loops clients as managed training jobs, manage Loops runs and checkpoints, and report GPU usage. |
| [`baseten truss`](/reference/cli/baseten/truss) | Run truss commands through `uv tool run` with credential forwarding. |
| [`baseten version`](/reference/cli/baseten/version) | Print Baseten CLI version information. |
| [`baseten whoami`](/reference/cli/baseten/whoami) | Show the authenticated user. |

## Use with AI agents

If you drive the Baseten CLI through a coding agent (Claude Code, Cursor, Codex), add this snippet to your project's `AGENTS.md` or `CLAUDE.md`. The CLI documents itself through `--help`, so the snippet only covers what an agent can't discover on its own: how to install, how to authenticate, and how to ask for machine-readable output.

````markdown AGENTS.md theme={"system"}
# Baseten CLI

The `baseten` CLI manages a Baseten workspace and its models. It never prompts
when stdin isn't a terminal, so it's safe to run headless.

## Install

Check for it first with `baseten version`. If missing, install with Homebrew
on macOS or Linux:

```sh
brew tap basetenlabs/baseten
brew trust --formula basetenlabs/baseten/baseten
brew install baseten
```

On other platforms, download the archive for your platform from
https://github.com/basetenlabs/baseten-cli/releases/latest, extract it, and
place `baseten` on your `PATH`.

## Authenticate

To log in, run `baseten auth login --web`: it prints a browser URL for the user
to open and waits for login to complete. For programmatic or CI use, set the
`BASETEN_API_KEY` environment variable instead (create a key at
https://app.baseten.co/settings/api_keys).

## Discover and script commands

- Discover commands with `baseten --help`, then drill down with
  `baseten <command> --help`. Add `--help-output` to see a command's JSON
  output shape and exit codes before parsing the output.
- Script with `--output json` (or `jsonl` for streamed commands) and filter
  with `--jq 'EXPR'`, for example `baseten model list --jq '.models[].id'`.
  `--jq` implies `--output json`.
- Use the `truss` CLI, not `baseten`, to author Chains. `baseten train` and
  `baseten loops` manage training jobs and Loops runs, and delegate to truss
  for the commands that need a Python config file (`train push`, `train init`,
  `loops checkpoint deploy`).
````

The CLI is one piece of the agent toolkit. For the Baseten skill and the MCP servers that let your agent operate a workspace and search these docs, see [Connect your coding agent](/agent-setup).

## Next steps

<CardGroup cols={2}>
  <Card title="Deploy from CI" icon="github" href="/deployment/ci-cd">
    Use `baseten model push` from GitHub Actions and other CI runners.
  </Card>

  <Card title="Compare with Truss" icon="scale-balanced" href="/reference/cli">
    See when to reach for `baseten` vs `truss` for each task.
  </Card>
</CardGroup>