The Beam CLI is the primary way you’ll interact with the Beam runtime.

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

Setup Credentials


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

beam config
Usage: beam config [OPTIONS] COMMAND [ARGS]...

  Manage configuration contexts.

  -h, --help  Show this message and exit.

  create  Create a new context.
  delete  Delete a context.
  list    Lists available contexts.
  select  Set a default context.


Create a new context.

beam config create [NAME]
$ beam config create prod-env

Context Name [prod-env]:
Gateway Host []:
Gateway Port [443]:
Added new context πŸŽ‰!


Delete a saved context.

beam config delete [NAME]
$ beam config delete prod-env

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


Lists saved contexts.

beam config list
$ beam config list

  Name      Host                       Port   Token
  default   443    qONcMO...
  staging   443    qONcMO...


Set the default context.

beam config select [NAME]
$ beam config select staging-env

Default context updated with 'staging-env'.



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

beam deploy [FILE:FUNCTION] --name [APP-NAME]
$ beam deploy create --name inference-app

=> Building image
=> Using cached image
=> Syncing files
=> Files synced
=> Deploying endpoint
=> Deployed πŸŽ‰


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


Stops a deployment.

beam deployment stop [DEPLOYMENT-ID]
$ beam deployment stop c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Stopped c7b9fdaa-a25a-4db0-a825-c31f94c91c3f


Serve a Preview App

Creates a temporary deployment preview.

beam serve [FILE:FUNCTION]
$ beam serve

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

=> Invocation details

curl -X POST '' \
-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...


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.

Storage Volumes

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

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.

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

Remove Files from Volumes

Remove a file from a volume.

beam rm [FILE]
=> weights/ (1 object deleted)

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


Ignoring Folders