CLI reference | Beaker Docs

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

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:

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.

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

The path must point to a file inside source_dir.

Sign in