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.

You can use the --help flag to get information about any command.

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 Beam SDK and CLI in your Python environment.

pip install beam-client

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

Setup Credentials

Beam will create a credentials file in ~/.beam/config.ini. When you run beam config create, your API keys will be saved to this file.

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'.

Deployment

Create

Deploys your app and creates a persistent web endpoint to access it.

You can run this command with beam deploy [...] or beam deploy create [...].

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

$ beam deploy create 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, taskqueue, 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 [SOURCE] [DEST]

$ beam mv file.txt files/text-files

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

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

You can stream logs from a task, deployment, or a container to your shell.

Deployment

Streams logs for a deployment.

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

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

$ beam logs --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 --task-id [TASK-ID]

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

Container

Streams logs for a container.

beam logs --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 --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
 ──────────────────────
  A100-40       ✅
  A6000         ✅
  A10G          ✅
  H100          ✅

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

​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

​Secret

​List Secrets

​Create a Secret

​Show a Secret

​Modify a Secret

​Delete a Secret

​Logs

​Deployment

​Task

​Container

​Stub ID

​Machine

​List

​Helpers and utils

​Ignore Local Files

Most Common Commands

Installation

Setup Credentials

Config

Create

Delete

List

Select

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

Secret

List Secrets

Create a Secret

Show a Secret

Modify a Secret

Delete a Secret

Logs

Deployment

Task

Container

Stub ID

Machine

List

Helpers and utils

Ignore Local Files