The Beam CLI is the primary way you’ll interact with the Beam runtime. If you’re using Beam, you’ll need it. We have installation instructions to guide you through the initial setup.

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

beam configure



Deploys your app based on the app decorator provided:

beam deploy

By default, your browser will automatically open the Beam Web UI whenever you deploy something.

You can disable the browser from opening by sourcing this environment variable in your shell:



Runs can be started with the beam run CLI command, by passing in a the name of a Python file and a function name.

beam run

The function logs will stream to stdout. Feel free to close your terminal window. The task will continue to run asynchronously, and you can view the logs and any outputs in the web dashboard.

Deployment Previews


Serve functions like an Ngrok server that live-reloads as you work. Beam monitors changes in your local file system and forwards the remote container logs to your local shell.

beam serve

When you run this command, you’ll see a URL printed in your shell. Serve URLs are public and authenticated with your Beam credentials.

user@MacBook stable-diffusion-gpu % beam serve
 i  Using cached image.
 ✓  App initialized.
 i  Uploading files...
 ✓  Container scheduled, logs will appear below.
 ✓  🏁 Started gateway server at

By default, Beam will sync all the files in your working directory to the remote container. This allows you to use the files you have locally while developing. If you want to prevent some files from getting uploaded, you can create a .beamignore.

You can then call the gateway URL to test your function, end-to-end. The remote session will spin down automatically after 10 minutes of inactivity.


Lists all running serve sessions.

beam serve list


Terminates an active serve session.

beam serve stop [serve-id]

Remote Development Sessions


Starts a remote runtime using the App() definition provided.

beam start


You can prefix any command with remote to force a command to run in the remote runtime.

remote ./


Disconnect from the runtime.


Storage Volumes

List Volumes

List all volumes mounted to your apps.

beam volume list

List Volume Contents

List all contents of a volume.

beam volume ls [volume] [flags]


Upload a file to a volume.

beam volume upload [volume] [file path] -a [app name]

If uploading to a Persistent Volume, the app name must be provided using the -a flag:

beam volume upload my_volume some_file.png -a the_app

If uploading to a Shared Volume, the app flag can be excluded.


Download a file from a volume.

beam volume download [volume] [path in volume] [local path] -a [app name]

Helpers and utils


Generate an autocompletion script for Beam for the shell you’re developing in. Includes support for bash, powershell, zsh, and fish.

beam completion zsh


Prints the version of the CLI installed.

beam version


Updates the CLI to the latest version.

beam update

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