***

title: CLI Getting Started
description: >-
Install and configure the NVIDIA Brev CLI for terminal-based GPU instance
management.
-----------

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

## Installation

### macOS

```bash
# Add the Brev tap and install
brew install brevdev/homebrew-brev/brev

# Verify installation
brev --version
```

### Linux

```bash
# 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](https://learn.microsoft.com/en-us/windows/wsl/install) installed and configured
* Virtualization enabled in your BIOS settings
* Ubuntu 20.04 or later from the Microsoft Store

```powershell
# Install WSL with Ubuntu (run in PowerShell as admin)
wsl --install -d Ubuntu-22.04

# Restart your computer, then open Ubuntu and run:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/brevdev/brev-cli/main/bin/install-latest.sh)"
```

<Callout intent="info">
  **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.
</Callout>

## 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.

```bash
# 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

| Flag             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `--token`        | Authenticate with a token (for headless/CI environments) |
| `--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`  |

### brev logout

Remove stored credentials from your machine.

```bash
brev logout
```

### brev ssh-key

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

```bash
# 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

<Callout intent="success">
  **Connect by name, not IP**: Run `ssh my-instance` or `brev shell my-instance`. The CLI tracks the IP address for you.
</Callout>

### 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.         |

<Callout intent="tip">
  Run `brev refresh` after creating instances in the web console to sync them to your local CLI and SSH config.
</Callout>

## 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. |

<Callout intent="tip">
  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.
</Callout>

## What's Next

<CardGroup cols={2}>
  <Card title="Instance Management" icon="server" href="/cli/instance-management">
    Learn to list, start, stop, and delete instances.
  </Card>

  <Card title="Connectivity" icon="plug" href="/cli/connectivity">
    Connect through shell, VS Code, or port forwarding.
  </Card>
</CardGroup>