> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

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.

```bash theme={null}
pip install beam-client
```

You can find instructions for installing the CLI on Windows [here](/v2/getting-started/installation#windows).

## 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](/v2/reference/cli#setup-credentials) and saves a profile to `~/.beam/config.ini`

```bash theme={null}
beam config
```

```bash theme={null}
$ 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](https://platform.beam.cloud/settings/api-keys).

### Create

Create a new context.

```bash theme={null}
beam config create [NAME]
```

```bash theme={null}
$ beam config create prod-env

Context Name [prod-env]:
Gateway Host [gateway.beam.cloud]:
Gateway Port [443]:
Token: [YOUR-TOKEN]
Added new context 🎉!
```

<Info>
  If you are prompted to enter a value for `Gateway Host` or `Gateway Port`, you
  can leave both fields blank.
</Info>

### Delete

Delete a saved context.

```bash theme={null}
beam config delete [NAME]
```

```bash theme={null}
$ beam config delete prod-env

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

### List

Lists saved contexts.

```bash theme={null}
beam config list
```

```bash theme={null}
$ beam config list

  Name      Host                       Port   Token
 ───────────────────────────────────────────────────────
  default   gateway.beam.cloud   443    qONcMO...
  staging   gateway.beam.cloud   443    qONcMO...
```

### Select

Set the default context.

```bash theme={null}
beam config select [NAME]
```

```bash theme={null}
$ beam config select staging-env

Default context updated with 'staging-env'.
```

### Specifying Context

Most commands support the `--context` (or `-c`) flag, which allows you to specify which config profile to use for that command. This is useful when working with multiple environments (e.g., development, staging, production).

```bash theme={null}
beam deploy app.py:handler --context staging
beam task list -c production
beam volume list --context dev
```

If no context is specified, the default context (set via `beam config select`) will be used.

## Deployment

### Create

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

<Note>
  You can run this command with `beam deploy [...]` or `beam deploy create   [...]`.
</Note>

```bash theme={null}
beam deploy [FILE:FUNCTION] --name [APP-NAME]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam deployment list
```

```bash theme={null}
$ 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.

```bash theme={null}
beam deployment stop [DEPLOYMENT-ID]
```

```bash theme={null}
$ beam deployment stop c7b9fdaa-a25a-4db0-a825-c31f94c91c3f

Stopped c7b9fdaa-a25a-4db0-a825-c31f94c91c3f
```

### Start

Starts an inactive deployment.

```bash theme={null}
beam deployment start [DEPLOYMENT-ID]
```

```bash theme={null}
$ beam deployment start c555edd8-3f10-4b54-ac1c-4e1e5e10eabd

Starting c555edd8-3f10-4b54-ac1c-4e1e5e10eabd
```

### Delete

Deletes a deployment.

```bash theme={null}
beam deployment delete [DEPLOYMENT-ID]
```

```bash theme={null}
$ 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.

```bash theme={null}
$ 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`:

```bash theme={null}
beam shell --container-id <CONTAINER_ID>
```

# Serve

### Create a Preview Environment

Creates a temporary deployment preview.

```bash theme={null}
beam serve [FILE:FUNCTION]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam container list
```

```bash theme={null}
$ 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.

```bash theme={null}
beam container stop [CONTAINER-ID]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam task list
```

```bash theme={null}
$ 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.

```bash theme={null}
beam task stop [TASK-ID]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam volume create [VOLUME-NAME]
```

```bash theme={null}
$ beam volume create weights

  Name       Created At    Updated At    Workspace Name
 ───────────────────────────────────────────────────────
  weights   May 07 2024   May 07 2024   cf2db0
```

### Delete a Volume

```bash theme={null}
beam volume delete [VOLUME-NAME]
```

```bash theme={null}
$ beam volume delete model-weights

Any apps (functions, endpoints, task queue, 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.

```bash theme={null}
beam volume list
```

```bash theme={null}
$ 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.

```bash theme={null}
beam ls [VOLUME-NAME]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam cp [LOCAL-PATH] beam://[VOLUME-NAME]
```

```bash theme={null}
=> weights (copying 1 object)
[LennonBeatlemania.pth] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.3/1.3 kB 0:00:00
```

### Move Files in Volumes

Move files around a volume.

```bash theme={null}
beam mv [SOURCE] [DEST]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam rm [FILE]
```

```bash theme={null}
=> weights/app.py (1 object deleted)
app.py
```

### Downloading Data

You can download directories and individual files.

```bash theme={null}
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:

```python theme={null}
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.

```bash theme={null}
beam secret list
```

```bash theme={null}
$ 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

```bash theme={null}
beam secret create [KEY] [VALUE]
```

```bash theme={null}
$ beam secret create AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Created secret with name: 'AWS_ACCESS_KEY'
```

### Show a Secret

Shows the value of a secret.

```bash theme={null}
beam secret show [KEY]
```

```bash theme={null}
$ beam secret show AWS_ACCESS_KEY

=> Secret 'AWS_ACCESS_KEY': ASIAY34FZKBOKMUTVV7A
```

### Modify a Secret

Modifies the value of a secret.

```bash theme={null}
beam secret modify [KEY] [VALUE]
```

```bash theme={null}
$ beam secret modify AWS_ACCESS_KEY ASIAY34FZKBOKMUTVV7A

=> Modified secret 'AWS_ACCESS_KEY'
```

### Delete a Secret

Permanently deletes a secret.

```bash theme={null}
beam secret delete [KEY]
```

```bash theme={null}
$ 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.

```bash theme={null}
beam logs --deployment-id [DEPLOYMENT-ID]
```

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

```bash theme={null}
$ 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.

```bash theme={null}
beam logs --task-id [TASK-ID]
```

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

### Container

Streams logs for a container.

```bash theme={null}
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.

```bash theme={null}
beam logs --stub-id [STUB-ID]
```

## Machine

Manage the machines available on Beam.

### List

List the available GPUs at any given moment.

```bash theme={null}
$ beam machine list

  GPU Type   Available
 ──────────────────────
  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`](https://git-scm.com/docs/gitignore)

**Ignoring Files**

```
do_not_sync.txt
.DS_Store
```

**Ignoring Folders**

```
images/*
node_modules/*
```