CLI Getting Started | NVIDIA Brev Documentation

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
bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"
# Verify installation
brev --version

If the installer exits with Error: Failed to fetch release info from GitHub API., refer to Resolving GitHub API Rate Limit Errors below.

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

# Install WSL with Ubuntu (run in PowerShell as admin)
wsl --install -d Ubuntu-22.04
# Restart your computer, then open Ubuntu and run:
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.

Resolving GitHub API Rate Limit Errors

The Linux and Windows (WSL) installers retrieve release metadata from the GitHub API before downloading the binary. GitHub limits unauthenticated requests to 60 per hour, counted per source IP address rather than per user. Shared egress IP addresses, including corporate NAT gateways, VPN exit nodes, cloud NAT, and CI runner pools, commonly exhaust this allowance, causing the installer to exit with the following error:

Error: Failed to fetch release info from GitHub API.

Resolve the error using any of the following solutions.

Change your outbound network route

If you are connected to a VPN, turn it off and re-run the installer. A VPN exit node is shared with every other user on that server, so its allowance is frequently already spent.
Change the VPN location to a different country, region, or server if you must stay connected. Each location has its own IP address and its own separate allowance.
Remove any configuration that forces traffic through a shared egress IP address, such as a proxy or a corporate network policy.

Export a GitHub token

Generate a personal access token at GitHub personal access token settings. Either a classic token with every scope left unchecked, or a fine-grained token with Repository access set to Public repositories (read-only).
Export the token, then re-run the installer.

export GITHUB_TOKEN="<TOKEN>"

Do not run the installer with sudo. It resets the environment, so GITHUB_TOKEN and your gh credentials are not passed through to the script. The installer writes to ~/.local/bin and does not require root.

Authenticate with the GitHub CLI

Log in with gh, then confirm a token was generated with gh auth token.
The installer detects and uses this token automatically, so no further configuration is required.

gh auth login
gh auth token

Authenticating the request raises the limit to 5,000 requests per hour, counted against your GitHub account instead of the shared IP address.

For more details, see CLI Install Fails with GitHub Rate Limit.

Authentication

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 your user authentication token (JWT)
brev login --token "<TOKEN>"
# Skip browser auto-open
brev login --skip-browser

Copy the token-based login command from CLI settings in the Brev Console. This uses your user authentication token (JWT), which is separate from a Brev API key.

Flags

Flag	Description
`--token <TOKEN>`	Authenticate with your user authentication token (JWT)
`--api-key <API_KEY>`	Save a Brev API key and select its organization automatically
`--skip-browser`	Print URL instead of auto-opening browser.
`--email`	Email to use for authentication (NVIDIA auth only)
`--auth`	Authentication provider: `nvidia` (default) or `legacy`

API key authentication

Use a Brev API key for scripts and CI without a browser login.

API keys are scoped to one organization. To work in another organization, use a key from that organization or switch back to user authentication.

Choose one of these methods:

# Save the key for future CLI sessions
brev login --api-key "<API_KEY>"
# Use a key for commands in the current shell session
export BREV_API_KEY="<API_KEY>"
brev ls
# Use a key for a single command
brev ls --api-key "<API_KEY>"

brev login --api-key saves the key in ~/.brev/credentials.json and selects its organization automatically. Using BREV_API_KEY or passing --api-key to a command such as brev ls does not save the key.

brev login --api-key requires a key value and cannot be combined with --token, --skip-browser, --email, or --auth. Use user login for SSH workflows; API key login does not set up your user SSH keys.

brev logout

Remove stored credentials from your machine.

brev logout

This removes saved credentials but does not revoke an API key or clear BREV_API_KEY from your shell. Run unset BREV_API_KEY to stop using an exported key. To switch back to user authentication, unset the variable and run brev login.

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 a user login, the CLI:

Downloads your SSH key to ~/.brev/brev.pem
Adds your instances to ~/.brev/ssh_config
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/

File	Purpose
`brev.pem`	Your SSH private key.
`ssh_config`	SSH entries for all your instances.
`credentials.json`	Your authentication tokens and any saved Brev API key.

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.

Component	Description
Container	Your development environment with Python, CUDA, etc. Default SSH target.
Host	The underlying GPU VM. Use `--host` flag to access.
workspace	Your 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.