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

Config

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

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

  Manage configuration contexts.

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

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

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 πŸŽ‰!

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

Deploy

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

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

Serve

Serve a Preview App

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

Tasks

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.

beam cp [LOCAL-PATH] [VOLUME-NAME]
=> 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/app.py (1 object deleted)
app.py

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/*