CLI Reference

CLI Getting Started

View as Markdown

Install and configure the Brev CLI for terminal-based GPU instance management.

Installation

macOS

$# Add the Brev tap and install
$brew install brevdev/homebrew-brev/brev
$
$# Verify installation
$brev --version

Linux

$# Download and run the installer
$sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"
$
$# Verify installation
$brev --version

Windows (WSL)

Brev supports Windows through the Windows Subsystem for Linux (WSL).

Prerequisites:

  • WSL installed and configured
  • Virtualization enabled in your BIOS settings
  • Ubuntu 20.04 or later from the Microsoft Store
1# Install WSL with Ubuntu (run in PowerShell as admin)
2wsl --install -d Ubuntu-22.04
3
4# Restart your computer, then open Ubuntu and run:
5sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"

BIOS Virtualization: If WSL fails to start, ensure virtualization (VT-x/AMD-V) is enabled in your BIOS settings. The exact steps vary by motherboard manufacturer.

Authentication

brev login

Authenticate with your Brev account. Opens a browser window for OAuth login and creates the ~/.brev/ directory with your credentials and SSH keys.

$# Standard login (opens browser)
$brev login
$
$# Login with token (for headless/CI environments)
$brev login --token
$
$# Skip browser auto-open
$brev login --skip-browser

Flags

FlagDescription
--tokenAuthenticate with a token (for headless/CI environments)
--skip-browserPrint URL instead of auto-opening browser.
--emailEmail to use for authentication (NVIDIA auth only)
--authAuthentication provider: nvidia (default) or legacy

brev logout

Remove stored credentials from your machine.

$brev logout

brev ssh-key

Display your Brev SSH public key. Use this to add to Git providers like GitHub or GitLab.

$# Display your public SSH key
$brev ssh-key
$
$# Copy to clipboard (macOS)
$brev ssh-key | pbcopy

How the CLI Manages SSH

The Brev CLI handles all SSH configuration automatically. You never need to:

  • Track instance IP addresses
  • Manage SSH keys
  • Edit SSH config files

After logging in, the CLI:

  1. Downloads your SSH key to ~/.brev/brev.pem
  2. Adds your instances to ~/.brev/ssh_config
  3. Keeps the config in sync as instances start and stop

Connect by name, not IP: Run ssh my-instance or brev shell my-instance. The CLI tracks the IP address for you.

What’s in ~/.brev/

FilePurpose
brev.pemYour SSH private key.
ssh_configSSH entries for all your instances.
credentials.jsonYour authentication tokens.

Run brev refresh after creating instances in the web console to sync them to your local CLI and SSH config.

Understanding Your Environment

When you connect to a Brev instance, you’re connecting to a containerized environment running on a GPU VM.

ComponentDescription
ContainerYour development environment with Python, CUDA, etc. Default SSH target.
HostThe underlying GPU VM. Use --host flag to access.
workspaceYour persistent workspace at /home/ubuntu/workspace. Files here survive stops.

Store all your work in /home/ubuntu/workspace and push to Git regularly. This directory persists when you stop an instance, but is deleted when you delete the instance.

What’s Next

Instance Management

Learn to list, start, stop, and delete instances.

Connectivity

Connect through shell, VS Code, or port forwarding.