The beam CLI is a command-line utility that lets you work with Beam using beam commands, from uploading files to volumes to deploying your applications. Use --help for command syntax and beam deploy --help-all for advanced deployment options. For persistent Linux machines, see the Virtual machines CLI reference.

Most Common Commands

You’ll be using these a lot!

beam deploy – deploy an app to the cloud
beam shell – SSH into a container to debug it interactively
beam serve – create a temporary live preview of your app
beam logs – stream logs from a task, container, or deployment

Installation

This installs the CLI in an isolated environment. Install beam-client separately in your project environment to import beam from Python.

uv tool install beam-client

You can find instructions for installing the CLI on Windows here.

Setup Credentials

beam login
beam whoami
beam doctor

On a remote machine, use beam login --no-browser. Credentials are saved in ~/.beam/config.ini. See authentication for tokens and CI.

Config

Configures your Beam API keys and saves a profile to ~/.beam/config.ini

beam config

$ beam config create prod

Context Name [prod]:
Gateway Host [gateway.beam.cloud]:
Gateway Port [443]:
Token:

Context Name (required) — the name of the profile i.e. prod or staging.
Gateway Host (optional) — used only for self-hosting. If you are using the beam.cloud, you can leave this blank.
Gateway Port (optional) — used only for self-hosting. If you are using the beam.cloud, you can leave this blank.
Token (required) — your API token, found on this page of the dashboard.

Create

Create a new context.

beam config create [NAME]

$ beam config create prod-env

Context Name [prod-env]:
Gateway Host [gateway.beam.cloud]:
Gateway Port [443]:
Token: [YOUR-TOKEN]
Added new context!

If you are prompted to enter a value for Gateway Host or Gateway Port, you can leave both fields blank.

Delete

Delete a saved context.

beam config delete [NAME]

$ beam config delete prod-env

Do you want to continue? [y/N]: y
Deleted context prod.

List

Lists saved contexts.

beam config list

$ beam config list

  Name      Host                       Port   Token
 ───────────────────────────────────────────────────────
  default   gateway.beam.cloud   443    qONcMO...
  staging   gateway.beam.cloud   443    qONcMO...

Select

Set the default context.

beam config select [NAME]

$ beam config select staging-env

Default context updated with 'staging-env'.

Specifying Context

Most commands support the --context (or -c) flag, which allows you to specify which config profile to use for that command. This is useful when working with multiple environments (e.g., development, staging, production).

beam deploy app.py:handler --context staging
beam task list -c production
beam volume list --context dev

If no context is specified, the default context (set via beam config select) will be used.

Deployment

Create

Deploys a Python handler, Dockerfile, or registry image. HTTP workloads return a URL; background workers without ports do not. See container hosting.

beam deploy [FILE:FUNCTION] --name [APP-NAME]

$ beam deploy app.py:handler --name inference-app

=> Building image
=> Using cached image
=> Syncing files
=> Files synced
=> Deploying endpoint
=> Deployed

List

Lists all deployments.

beam deployment list

$ beam deployment list

  ID                 Name              Active   Version   Created At    Updated At    Stub Name         Workspace Name
 ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  9c9e99aa-a64e-4…   whisper-stt       Yes            1   1 day ago     1 day ago     endpoint/deplo…   cf2db0
  e1831baa-e4a9-4…   inference-app     Yes            2   5 days ago    5 days ago    endpoint/deplo…   cf2db0
  6983cfe2-abf7-4…   vllm-app          Yes            2   7 days ago    7 days ago    endpoint/deplo…   cf2db0

  3 items

Stop

Stops a deployment.

beam deployment stop [DEPLOYMENT-ID]

$ beam deployment stop c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Stopped c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Start

Starts an inactive deployment.

beam deployment start [DEPLOYMENT-ID]

$ beam deployment start c555edd8-3f10-4b54-ac1c-4e1e5e10eabd

Starting c555edd8-3f10-4b54-ac1c-4e1e5e10eabd

Delete

Deletes a deployment.

beam deployment delete [DEPLOYMENT-ID]

$ beam deployment delete c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Deleted deployment c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Shell

SSH Into Containers

Allows you to interactively access a container on Beam.

$ beam shell app.py:handler

=> Building image
=> Using cached image
=> Syncing files
Reading .beamignore file
=> Files synced

Welcome to Ubuntu 22.04.5 LTS (GNU/Linux 6.8.0-51-generic x86_64)

root@runc:/mnt/code#

You can also shell into a running container, by passing in a container_id:

beam shell --container-id <CONTAINER_ID>

Serve

Create a Preview Environment

Creates a temporary deployment preview.

beam serve [FILE:FUNCTION]

$ beam serve app.py:predict

=> Building image
=> Using cached image
=> Syncing files
Reading .beamignore file
=> Files synced

=> Invocation details

curl -X POST 'https://app.beam.cloud/endpoint/id/55108039-e3bf-409b-bad5-f4982b2f1c02' \
-H 'Accept: */*' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Connection: keep-alive' \
-H 'Authorization: Bearer [YOUR_AUTH_TOKEN]' \
-H 'Content-Type: application/json' \
-d '{}'

=> Watching /Users/beam for changes...
⠇ Serving endpoint...

Container

Manage the containers running in your account.

List

Lists all containers.

beam container list

$ beam container list

  ID                                                       Status    Stub Id                                Scheduled At
 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  function-ee5c046f-985f-40b7-a0fa-477794e0a052-6c0d5340   RUNNING   27d567fe-8bd3-41b4-bd5b-2e6ce1afb454   3 seconds ago

  1 item(s)

Stop

Terminate a running container.

beam container stop [CONTAINER-ID]

$ beam container stop function-ee5c046f-985f-40b7-a0fa-477794e0a052-6c0d5340

Stopped container.

Task

Any code you run on Beam creates a task. Any time you run a function or invoke an API, a task is created.

List Tasks

Lists all tasks.

beam task list

$ beam task list

  Task ID             Status     Started At       Ended At         Container ID        Stub Name           Workspace Name
 ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  29d739d5-624f-41…   COMPLETE   29 minutes ago   29 minutes ago   endpoint-b4e9a64…   endpoint/deploym…   cf2db0
  f45fe342-0bff-4e…   COMPLETE   35 minutes ago   35 minutes ago   endpoint-c1dd0b6…   endpoint/deploym…   cf2db0
  4b9a1b6f-e34d-4d…   COMPLETE   1 day ago        1 day ago        endpoint-05fb7c9…   endpoint/deploym…   cf2db0
  38910b63-8c8a-42…   COMPLETE   1 day ago        1 day ago        endpoint-05fb7c9…   endpoint/deploym…   cf2db0
  cf051d10-fa28-42…   COMPLETE   1 day ago        1 day ago        endpoint-05fb7c9…   endpoint/deploym…   cf2db0

Stop a Task

Stops a task.

beam task stop [TASK-ID]

$ beam task stop c6d9e4a3-9262-485a-a7bb-a72980008c02

Stopped task c6d9e4a3-9262-485a-a7bb-a72980008c02.

Volume

Beam allows you to create highly-available storage volumes that can be used across tasks. You might use volumes for things like storing model weights or large datasets.

Create a Volume

Creates a volume.

beam volume create [VOLUME-NAME]

$ beam volume create weights

  Name       Created At    Updated At    Workspace Name
 ───────────────────────────────────────────────────────
  weights   May 07 2024   May 07 2024   cf2db0

Delete a Volume

beam volume delete [VOLUME-NAME]

$ beam volume delete model-weights

Any apps (functions, endpoints, task queue, etc) that
refer to this volume should be updated before it is deleted.
Are you sure? (y/n) [n]: y

Deleted volume model-weights

List Volumes

List all volumes mounted to your apps.

beam volume list

$ beam volume list

  Name                                Size   Created At   Updated At   Workspace Name
 ─────────────────────────────────────────────────────────────────────────────────────
  weights                       240.23 MiB   2 days ago   2 days ago   cf2db0

  1 volumes | 240.23 MiB used

List Volume Contents

List all contents of a volume.

beam ls [VOLUME-NAME]

$ beam ls weights

  Name                               Size   Modified Time    IsDir
 ──────────────────────────────────────────────────────────────────
  .locks                           0.00 B   29 minutes ago   Yes
  models--facebook--opt-125m   240.23 MiB   28 minutes ago   Yes

  2 items | 240.23 MiB used

Copy Files to Volumes

Copies a file to a volume.

beam cp [LOCAL-PATH] beam://[VOLUME-NAME]

=> weights (copying 1 object)
[LennonBeatlemania.pth] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.3/1.3 kB 0:00:00

Move Files in Volumes

Move files around a volume.

beam mv beam://[VOLUME]/[SOURCE] beam://[VOLUME]/[DEST]

$ beam mv beam://myvol/file.txt beam://myvol/files/text-files/file.txt

Moved file.txt to files/text-files/file.txt

Remove Files from Volumes

Remove a file from a volume.

beam rm [FILE]

=> weights/app.py (1 object deleted)
app.py

Downloading Data

You can download directories and individual files.

beam cp beam://myvol/file.txt .             # beam://myvol/file.txt => ./file.txt
beam cp beam://myvol/file.txt file.new      # beam://myvol/file.txt => ./file.new
beam cp beam://myvol/mydir .                # beam://myvol/mydir/file.txt => ./file.txt

Disk

Durable disks are persistent, node-local storage for stateful workloads such as databases. Disks are created automatically when an app that declares them is run or deployed, and can also be managed directly from the CLI.

Create a Disk

Creates a disk, or returns the existing disk if one with that name already exists.

beam disk create [DISK-NAME] [--size SIZE] [--filesystem FS] [--mount-path PATH] [--format table|json]

$ beam disk create app-data --size 10Gi --mount-path /data

  Name       Size   Filesystem   Mount Path   Created At    Workspace Name
 ──────────────────────────────────────────────────────────────────────────
  app-data   10Gi   ext4         /data        Sep 13 2026   85cfa7

--size defaults to 10Gi and --filesystem to ext4.

List Disks

List all disks in your workspace.

beam disk list [--format table|json]

$ beam disk list

  Name          Size   Filesystem   Mount Path   Created At    Workspace Name
 ───────────────────────────────────────────────────────────────────────────────
  redis-data    5Gi    ext4         /data        Jul 13 2026   85cfa7
  app-data      10Gi   ext4         /data        Sep 13 2026   85cfa7

  2 disks

List Disk Snapshots

List the snapshots taken of a disk. Omit the disk name to list snapshots for every disk in the workspace.

beam disk snapshots [DISK-NAME] [--format table|json]

$ beam disk snapshots redis-data

  Disk Name    Status      Format         Generation            Logical Size   Stored Size   Created At
 ─────────────────────────────────────────────────────────────────────────────────────────────────────────
  redis-data   available   redis.aof.v1   1783980128619331915   234.00 B       234.00 B      Jul 13 2026
  redis-data   available   redis.aof.v1   1783979768654042369   340.00 B       340.00 B      Jul 13 2026

  2 snapshots

Delete a Disk

Deletes a disk from your workspace. Snapshots of the disk are kept.

beam disk delete [DISK-NAME] [-y]

$ beam disk delete app-data

Any apps or services (functions, endpoints, databases, etc) that
refer to this disk should be updated before it is deleted.
Are you sure? [y/N]: y

✓ Deleted disk: app-data

Secret

Secrets and environment variables can be injected into the containers that run your apps. After a secret is saved, it can be used in your application code like this:

from beam import function


@function(secrets=["AWS_ACCESS_KEY"])
def handler():
    import os

    my_secret = os.environ["AWS_ACCESS_KEY"]
    print(f"Secret: {my_secret}")

List Secrets

Lists all secrets that exist.

beam secret list

$ beam secret list

  Name             Last Updated     Created
 ──────────────────────────────────────────────────
  AWS_KEY          19 hours ago     19 hours ago
  AWS_ACCESS_KEY   20 seconds ago   20 seconds ago
  AWS_REGION       7 seconds ago    7 seconds ago

  3 items

Create a Secret

Creates a secret

beam secret create [KEY] [VALUE]

$ beam secret create AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Created secret with name: 'AWS_ACCESS_KEY'

Show a Secret

Shows the value of a secret.

beam secret show [KEY]

$ beam secret show AWS_ACCESS_KEY

=> Secret 'AWS_ACCESS_KEY': ASIAY34FZKBOKMUTVV7A

Modify a Secret

Modifies the value of a secret.

beam secret modify [KEY] [VALUE]

$ beam secret modify AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Modified secret 'AWS_ACCESS_KEY'

Delete a Secret

Permanently deletes a secret.

beam secret delete [KEY]

$ beam secret delete AWS_ACCESS_KEY

=> Deleted secret 'AWS_ACCESS_KEY'

Logs

Logs return the last 100 lines. Use beam logs web --follow to stream, or select an ID below. See logs and metrics for filters.

Deployment

Streams logs for a deployment.

beam logs --follow --deployment-id [DEPLOYMENT-ID]

You can find the deployment ID by running beam deployment list.

$ beam logs --follow --deployment-id 2089b5b5-9b2a-450e-9a56-a50d4f0a8d4c

Starting task worker[0]
Worker[0] ready
Running task <25156946-2c3a-4900-8a2c-568f162493a7>
Task completed <25156946-2c3a-4900-8a2c-568f162493a7>, took 3.4570693s
Spinning down taskqueue

Task

Streams logs for a task.

beam logs --follow --task-id [TASK-ID]

You can find the task ID by running beam task list.

Container

Streams logs for a container.

beam logs --follow --container-id [CONTAINER-ID]

You can find the container ID by running beam container list.

Stub ID

Streams logs for a stub ID.

beam logs --follow --stub-id [STUB-ID]

Machine

Manage the machines available on Beam.

List

List the available GPUs at any given moment.

$ beam machine list

  GPU Type   Available
 ──────────────────────
  A10G          Yes
  H100          Yes

Reserve

Reserves on-demand hardware into a compute pool. In a terminal, it lists the cheapest offers and asks you to pick one. With --yes, or when the output is piped, it reserves the cheapest offer without prompting.

beam machine reserve --gpu GPU [--nodes N] [--ttl DURATION] [--name POOL] [--max-spend USD] [-y]

# Cheapest A6000 for two hours, no prompts
beam machine reserve --gpu A6000 --ttl 2h --yes

# Two H100 nodes in a pool named "training", kept until you release them
beam machine reserve --gpu H100 --nodes 2 --ttl indefinite --name training

The pool is named ondemand-<gpu> unless you pass --name. --ttl takes a duration such as 45m, 6h, or 2d, or indefinite, which starts with a 30-day lease. If you omit --max-spend, it’s calculated from the offer price and TTL.

Reserved nodes renew hourly past their TTL while your workspace has credit, and you’re billed until they’re released. See how reserved nodes are billed.

Release

Releases reserved hardware and stops billing for it.

beam machine release [MACHINE-ID] [--pool POOL] [-y]

# Pick what to release interactively
beam machine release

# Release everything reserved under a pool
beam machine release --pool ondemand-a6000

# Release a single machine by ID
beam machine release 9a8b7c6d

Get machine IDs from beam pool machines.

Pool

Manage compute pools, groups of dedicated machines that your apps can run on. Route an app to a pool with the pool argument in your code, or with beam deploy --pool <name>.

List Pools

beam pool list [--limit N] [--format table|json] [--watch]

$ beam pool list

  Pool         Type      Status   Machines   Compute
 ────────────────────────────────────────────────────────────
  H100-pool    private   active        0/0   1 node (H100)
  a4000-pool   private   active        0/0   1 node (A4000)
  my-pool      private   active        0/0   CPU

  3 items

With --format json, each pool includes its reservations, with lease and billing details. See Checking a Reservation.

Create a Pool

Creates a private pool for machines you attach yourself. You don’t have to run this first: beam pool join, beam pool scale, and beam machine reserve create the pool if it doesn’t exist.

beam pool create [NAME] [--gpu GPU]

Browse Offers

Lists the on-demand offers that match a pool shape, without reserving anything. For an interactive picker, use beam machine reserve.

beam pool offers [--gpu GPU] [--nodes N] [--provider PROVIDER] [--region REGION] [--ttl DURATION] [--max-spend USD] [--min-reliability SCORE] [--format table|json]

$ beam pool offers --gpu L4

  Provider    Region           Instance   Nodes   Compute                  $/hr      Available
 ───────────────────────────────────────────────────────────────────────────────────────────────
  shadeform   paris-france-5   L4             1   1x L4, 8CPU, 48.0GiB     $1.0450           2
  shadeform   paris-france-5   L4x2           1   2x L4, 16CPU, 96.0GiB    $2.0900           2

  2 items

Reserve Nodes

Reserves nodes into a named pool without prompting, which makes it the scriptable counterpart to beam machine reserve. --ttl and --max-spend are required. When you add nodes to an existing pool, the GPU type must match the pool’s.

beam pool scale [NAME] --ttl DURATION --max-spend USD [--gpu GPU] [--nodes N] [--provider PROVIDER] [--region REGION] [--min-reliability SCORE] [--offer-id ID]

# Reserve two Hetzner CPU nodes for six hours
beam pool scale web-cpu --provider hetzner --nodes 2 --ttl 6h --max-spend 5

# Reserve one L4 node and route a service to it
beam pool scale gpu-api --gpu L4 --nodes 1 --ttl 2h --max-spend 4
beam deploy --name api --dockerfile Dockerfile --pool gpu-api

--offer-id reserves a specific offer returned by beam pool offers.

List Machines

Lists the machines in your private pools, or in a single pool if you pass its name. The table shows each machine’s ID, state, capacity, load, public IP, and when it last checked in.

beam pool machines [NAME] [--limit N] [--format table|json]

Extend a Pool

Moves the lease end of every reserved node in a pool, or raises the pool’s spend cap. --ttl is measured from now, and only ever extends leases.

beam pool extend [NAME] [--ttl DURATION] [--max-spend USD]

# Keep a reservation alive for another 12 hours
beam pool extend ondemand-a6000 --ttl 12h

# Raise the spend cap on a long-lived reservation
beam pool extend ondemand-a6000 --max-spend 50

Delete a Pool

Deletes a pool, releasing all of its machines and reservations.

beam pool delete [NAME]

Join a Machine

Joins the machine you run it on to a private pool, creating the pool if it doesn’t exist.

beam pool join [NAME] [--gpu GPU] [--max-cpu N] [--max-memory SIZE] [--max-gpus N | --gpu-ids IDS] [--print-only]

# Join this machine to a private pool
beam pool join private-gpu

# Offer at most two GPUs and 32Gi of memory from this machine
beam pool join private-gpu --max-gpus 2 --max-memory 32Gi

# Print the join command without running it
beam pool join private-gpu --print-only

--max-cpu, --max-memory, --max-gpus, and --gpu-ids limit what the machine offers to the pool. Use either --max-gpus or --gpu-ids, not both.

Print a Join Command

Prints an install command that joins a machine to the pool. Use it to add a machine that doesn’t have the Beam CLI installed.

beam pool join-command [NAME] [--ttl DURATION]

The command contains a join token, so treat it like a secret. The token is valid for 30 minutes unless you pass --ttl.

Additional Workflows

Workflow	Commands and guide
Deployment readiness and rollouts	`beam deployment wait`, `beam deployment scale`; deployment lifecycle
Databases	`beam db postgres`, `beam db redis`, `beam db mysql`, `beam db mongo`; managed databases
App groups	`beam stack`; stacks
Reserved compute	`beam pool`; compute pools
Coding agents	`beam setup agent`, `beam mcp`; agent setup

Use --help on the command you need. Global options precede the subcommand, for example beam --context production --json deployment list.

Helpers and utils

Ignore Local Files

You can create a .beamignore file in your project’s root directory to tell Beam which local files and directories to ignore when syncing to Beam. This follows the conventions of .gitignore Ignoring Files

do_not_sync.txt
.DS_Store

Ignoring Folders

images/*
node_modules/*

​Most Common Commands

​Installation

​Setup Credentials

​Config

​Create

​Delete

​List

​Select

​Specifying Context

​Deployment

​Create

​List

​Stop

​Start

​Delete

​Shell

​SSH Into Containers

​Serve

​Create a Preview Environment

​Container

​List

​Stop

​Task

​List Tasks

​Stop a Task

​Volume

​Create a Volume

​Delete a Volume

​List Volumes

​List Volume Contents

​Copy Files to Volumes

​Move Files in Volumes

​Remove Files from Volumes

​Downloading Data

​Disk

​Create a Disk

​List Disks

​List Disk Snapshots

​Delete a Disk

​Secret

​List Secrets

​Create a Secret

​Show a Secret

​Modify a Secret

​Delete a Secret

​Logs

​Deployment

​Task

​Container

​Stub ID

​Machine

​List

​Reserve

​Release

​Pool

​List Pools

​Create a Pool

​Browse Offers

​Reserve Nodes

​List Machines

​Extend a Pool

​Delete a Pool

​Join a Machine

​Print a Join Command

​Additional Workflows

​Helpers and utils

​Ignore Local Files

Most Common Commands

Installation

Setup Credentials

Config

Create

Delete

List

Select

Specifying Context

Deployment

Create

List

Stop

Start

Delete

Shell

SSH Into Containers

Serve

Create a Preview Environment

Container

List

Stop

Task

List Tasks

Stop a Task

Volume

Create a Volume

Delete a Volume

List Volumes

List Volume Contents

Copy Files to Volumes

Move Files in Volumes

Remove Files from Volumes

Downloading Data

Disk

Create a Disk

List Disks

List Disk Snapshots

Delete a Disk

Secret

List Secrets

Create a Secret

Show a Secret

Modify a Secret

Delete a Secret

Logs

Deployment

Task

Container

Stub ID

Machine

List

Reserve

Release

Pool

List Pools

Create a Pool

Browse Offers

Reserve Nodes

List Machines

Extend a Pool

Delete a Pool

Join a Machine

Print a Join Command

Additional Workflows

Helpers and utils

Ignore Local Files