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.