CLI Reference
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
Login
Automatically add your API keys to your local machine.
$ beam login
=> Login from dashboard with code: U050LC
Authenticated π!
This command will open the Beam dashboard in your web browser and fire a callback that saves your Beam credentials to your local machine.
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
Delete
Deletes a deployment.
beam deployment delete [DEPLOYMENT-ID]
$ beam deployment delete c7b9fdaa-a25a-4db0-a825-c31f94c91c3f
Deleted deployment c7b9fdaa-a25a-4db0-a825-c31f94c91c3f
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] [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
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 create 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 β
A100-80 β
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/*
Was this page helpful?