CLI Reference

Instance Management

View as Markdown

Commands for managing the lifecycle of your GPU instances.

brev list

List workspaces and organizations.

# List instances in current organization
brev list
# List all organizations you belong to
brev list orgs
# List instances in a specific organization
brev list --org my-team

brev start

Start a stopped instance, or create a new one from a Git URL or local path.

brev start vs brev create: These commands are equivalent. Use brev start as it is the preferred command.

Start a Stopped Instance

brev start my-instance

Create from Git URL

# Create from GitHub
brev start https://github.com/user/repo.git
# With custom name
brev start https://github.com/user/repo.git --name my-project
# In a specific organization
brev start https://github.com/user/repo.git --org my-team

Create with GPU

# Default GPU (T4)
brev start https://github.com/user/repo.git
# Specify GPU type
brev start https://github.com/user/repo.git --gpu "n1-highmem-4:nvidia-tesla-a100:1"

GPU Type Format

The --gpu flag uses the format machine-type:gpu-type:count:

PartDescriptionExample
machine-typeCloud VM typen1-highmem-4
gpu-typeNVIDIA GPU modelnvidia-tesla-a100
countNumber of GPUs1

Refer to GPU Instances for available GPU types and pricing.

Create Empty Instance

brev start --name my-sandbox

Flags

FlagShortDescription
--name-nName for the new instance.
--org-oOrganization (overrides active org)
--gpu-gGPU instance type.
--detached-dRun in background without blocking.
--empty-eCreate empty instance (no Git repo)
--setup-script-sURL to setup script.
--setup-repo-rRepo containing setup script.
--setup-path-pPath to setup script.

Using Setup Scripts

Setup scripts run automatically after your instance starts. Use them to install dependencies or configure your environment.

# Run a setup script from URL
brev start https://github.com/user/repo.git --setup-script https://raw.githubusercontent.com/user/repo/main/setup.sh
# Run a script from within the repo
brev start https://github.com/user/repo.git --setup-repo . --setup-path ./scripts/setup.sh

Setup scripts run as the default user. Use sudo for system-level installations.

brev stop

Pause an instance. Data in /home/ubuntu/workspace persists between stops.

# Stop a single instance
brev stop my-instance
# Stop multiple instances
brev stop instance-1 instance-2 instance-3
# Stop all your instances
brev stop --all

Flags

FlagShortDescription
--all-aStop all your instances in the current org.

brev delete

Permanently remove an instance and all its data.

# Delete by name
brev delete my-instance
# Delete by ID
brev delete abc123def456
# Delete multiple instances
brev delete instance-1 instance-2

Deleting an instance is irreversible. All data is permanently lost.

brev refresh

Sync instances and update your local SSH configuration. The CLI manages SSH config automatically, but run this command to force an immediate sync.

brev refresh

What refresh does:

  1. Downloads instances created in the web console
  2. Updates ~/.brev/ssh_config with current instance IPs
  3. Ensures ~/.brev/brev.pem has correct permissions

After refresh, connect by name: Run ssh my-instance or brev shell my-instance. You never need to look up IP addresses.

When to refresh: After creating instances in the web console, after restarting a stopped instance (IP may change), or when SSH connections fail.

brev set

Change the active organization context. All subsequent commands will operate within this org.

brev set my-team

To switch organizations, you must be logged in. Use brev login first if needed.

What’s Next

Connectivity

Connect through shell, VS Code, or port forwarding.

Advanced Commands

Additional commands for power users.