> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.withbeaker.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.withbeaker.ai/docs/_mcp/server.

# CLI reference

Install the CLI with `pip install beaker-sdk`, or run it without installing: `uvx --from beaker-sdk beaker <command>`.

## Sign in

| Command | What it does |
| --- | --- |
| `beaker login` | Opens your browser so you can approve this machine, then saves your session |
| `beaker logout` | Signs out and deletes the saved session |
| `beaker auth status` | Shows who you're signed in as, and for which organization |

For CI and other unattended jobs, create an API key in the app and set it as `BEAKER_API_KEY`. The CLI picks the first of these it finds: `--api-key`, your saved session, then `BEAKER_API_KEY`.

## GitHub

| Command | What it does |
| --- | --- |
| `beaker github status` | Shows the GitHub App installations connected to your organization and the repositories they can see |
| `beaker github connect` | Opens the page where you install the Beaker GitHub App |
| `beaker github branches --repo owner/name` | Lists the branches Beaker can read, for `run trigger --ref` |

Installing the GitHub App and choosing which repositories it can see happens on GitHub.

## Agents

| Command | What it does |
| --- | --- |
| `beaker agent list [--json]` | Lists your agents with their repository and config path |
| `beaker agent setup NAME [--repo owner/name]` | Picks or creates an agent, links it to your repository, and saves its key in `.beaker/beaker.yaml` |
| `beaker agent create NAME --repo owner/name` | Creates an agent without prompts |
| `beaker agent edit NAME [--name ...] [--config-path ...]` | Renames an agent or changes its config path |
| `beaker agent env list` | Lists the environment variables saved for the agent |
| `beaker agent env set NAME --value-stdin` | Saves an encrypted environment variable for hosted runs |
| `beaker agent env delete NAME` | Removes an environment variable |

An agent that is linked to a repository can't be linked to a different one.

To pick an agent, Beaker uses `--agent`, then `BEAKER_AGENT_KEY`, then `agent_key` from your `beaker.yaml`.

## Datasets

| Command | What it does |
| --- | --- |
| `beaker dataset upload` | Uploads a dataset. Each upload is saved as a new, unchangeable revision |
| `beaker dataset list` | Lists your datasets and their revisions |
| `beaker dataset show REFERENCE` | Shows a dataset. `REFERENCE` is `name`, `name@revision` or `name@production` |
| `beaker dataset promote REFERENCE` | Marks a revision as the production dataset |

## Runs

| Command | What it does |
| --- | --- |
| `beaker run trigger --ref REF --dataset REFERENCE` | Starts a run from a branch in your GitHub repository |
| `beaker run status RUN_ID` | Shows progress, candidates and results. Add `--watch` to follow along |
| `beaker run list` | Lists recent runs |
| `beaker run cancel RUN_ID` | Cancels a run that's still going |
| `beaker run pull RUN_ID` | Downloads the candidates and results |
| `beaker model list` | Lists the models you can optimize with |

## Set up and check locally

These run on your machine.

| Command | What it does |
| --- | --- |
| `beaker init` | Creates `.beaker/beaker.yaml` and a starter integration in your repo |
| `beaker run smoke` | Checks that your integration and dataset load correctly, without running your agent or scoring it |
| `beaker onboarding status` | Shows which setup steps are done and what to do next |
| `beaker trace instrument` | Adds tracing to your code |
| `beaker trace inspect` | Prints a trace from a local run |
| `beaker trace doctor` | Fails if the latest local trace is incomplete |

`beaker init` keeps any config you already have. To use an integration in another file, pass `--integration-id <id> --target <path.py-or-module:attribute>`.

`beaker run smoke` loads your dataset (a local folder, or a hosted dataset revision) and checks every row. Add `--strict` for the checks Beaker runs before a hosted run. Use `--integration-id <id>` to pick an integration when your config has more than one.

## Configure hosted runs

### Python version

Hosted runs use Python 3.12 by default. Beaker reads `requires-python` from your project's `pyproject.toml` and picks the lowest version that fits. To set it yourself, use `environment_base`. The supported values are `debian_slim:3.12` and `debian_slim:3.13`:

```yaml
integrations:
  example:
    entrypoint: "beaker_integration:integration"
    environment_base: "debian_slim:3.13"
```

If `environment_base` doesn't match what your project needs, Beaker stops before building and tells you what to change.

### Installing a workspace package

If your integration lives in a uv workspace, set `pip_install_from` to the `pyproject.toml` of the package to install alongside your source folder. `beaker init` sets this for you.

```yaml
integrations:
  example:
    pip_install_from: "workspace/pyproject.toml"
```

The path must point to a file inside `source_dir`.