***

title: Instance Management
description: >-
Manage GPU instance lifecycle with Brev CLI - list, start, stop, delete, and
refresh commands.
-----------------

Commands for managing the lifecycle of your GPU instances.

## brev list

List workspaces and organizations.

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

<Callout intent="note">
  **`brev start` vs `brev create`**: These commands are equivalent. Use `brev start` as it is the preferred command.
</Callout>

### Start a Stopped Instance

```bash
brev start my-instance
```

### Create from Git URL

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

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

| Part         | Description      | Example             |
| ------------ | ---------------- | ------------------- |
| machine-type | Cloud VM type    | `n1-highmem-4`      |
| gpu-type     | NVIDIA GPU model | `nvidia-tesla-a100` |
| count        | Number of GPUs   | `1`                 |

<Callout intent="info">
  Refer to [GPU Instances](/concepts/gpu-instances) for available GPU types and pricing.
</Callout>

### Create Empty Instance

```bash
brev start --name my-sandbox
```

### Flags

| Flag             | Short | Description                         |
| ---------------- | ----- | ----------------------------------- |
| `--name`         | `-n`  | Name for the new instance.          |
| `--org`          | `-o`  | Organization (overrides active org) |
| `--gpu`          | `-g`  | GPU instance type.                  |
| `--detached`     | `-d`  | Run in background without blocking. |
| `--empty`        | `-e`  | Create empty instance (no Git repo) |
| `--setup-script` | `-s`  | URL to setup script.                |
| `--setup-repo`   | `-r`  | Repo containing setup script.       |
| `--setup-path`   | `-p`  | Path to setup script.               |

### Using Setup Scripts

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

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

<Callout intent="info">
  Setup scripts run as the default user. Use `sudo` for system-level installations.
</Callout>

## brev stop

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

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

| Flag    | Short | Description                                 |
| ------- | ----- | ------------------------------------------- |
| `--all` | `-a`  | Stop all your instances in the current org. |

## brev delete

Permanently remove an instance and all its data.

```bash
# Delete by name
brev delete my-instance

# Delete by ID
brev delete abc123def456

# Delete multiple instances
brev delete instance-1 instance-2
```

<Callout intent="warning">
  Deleting an instance is irreversible. All data is permanently lost.
</Callout>

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

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

<Callout intent="success">
  **After refresh, connect by name**: Run `ssh my-instance` or `brev shell my-instance`. You never need to look up IP addresses.
</Callout>

<Callout intent="tip">
  **When to refresh:** After creating instances in the web console, after restarting a stopped instance (IP may change), or when SSH connections fail.
</Callout>

## brev set

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

```bash
brev set my-team
```

<Callout intent="info">
  To switch organizations, you must be logged in. Use `brev login` first if needed.
</Callout>

## What's Next

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

  <Card title="Advanced Commands" icon="gear" href="/cli/advanced-commands">
    Additional commands for power users.
  </Card>
</CardGroup>