CLI Reference

Composable Workflows

View as Markdown

Brev CLI commands are designed to compose together using standard Unix pipes. Commands read instance names from stdin and output instance names to stdout.

Pipe Architecture

Sources produce instance names (one per line). Actions read names from stdin, perform operations, and output names to stdout for further chaining.

Output Modes

Commands automatically detect whether their output is going to a terminal or a pipe:

ModeBehaviorExample
Interactive (terminal)Formatted table with headers and colors.brev ls
Piped (stdout)Instance names only, one per line.brev ls | brev stop
JSON (--json)Structured JSON output.brev ls --json

Piping from brev ls

Use awk and grep to extract instance names from brev ls output:

$# Stop all running instances
$brev ls | awk '/RUNNING/ {print $1}' | brev stop
$
$# Delete all stopped instances
$brev ls | awk '/STOPPED/ {print $1}' | brev delete
$
$# Start all stopped instances
$brev ls | awk '/STOPPED/ {print $1}' | brev start
$
$# Open all running instances in Cursor
$brev ls | awk '/RUNNING/ {print $1}' | brev open cursor
$
$# Run nvidia-smi on all running instances
$brev ls | awk '/RUNNING/ {print $1}' | brev exec "nvidia-smi"

Filtering with grep

$# Stop instances matching a pattern
$brev ls | grep "test-" | awk '{print $1}' | brev stop
$
$# Delete old experiment instances
$brev ls | grep "experiment" | awk '{print $1}' | brev delete
$
$# Open all "dev-" instances
$brev ls | grep "^dev-" | awk '{print $1}' | brev open

Create-to-Access Chains

Chain brev search, brev create, and access commands into single pipelines:

$# Search, create, and open
$brev search --gpu-name A100 | brev create my-box | brev open cursor
$
$# Create and run a command
$brev create my-box | brev exec "nvidia-smi"
$
$# Create and run a setup script
$brev create my-box | brev exec @setup.sh
$
$# Create cluster and verify all nodes
$brev create my-cluster --count 3 | brev exec "hostname && nvidia-smi"

Batch Operations

Several commands accept multiple instance names as arguments:

$# Stop multiple instances
$brev stop instance1 instance2 instance3
$
$# Delete multiple instances
$brev delete instance1 instance2 instance3
$
$# Start multiple instances
$brev start instance1 instance2
$
$# Run on multiple instances
$brev exec instance1 instance2 instance3 "nvidia-smi"

The --all Flag

brev stop supports --all to stop every running instance:

$brev stop --all

Exit Codes for Batch Operations

When operating on multiple instances, commands return exit code 2 if some (but not all) operations fail. This lets you distinguish between full success, partial failure, and total failure in scripts.

Safety: Preview Before Destructive Operations

Always preview what a pipeline will affect before running destructive operations:

$# Preview what will be stopped
$brev ls | awk '/RUNNING/ {print $1}'
$
$# Then actually stop
$brev ls | awk '/RUNNING/ {print $1}' | brev stop

Pipe the output without the final destructive command first to verify the instance list. Then add | brev stop or | brev delete when you’re satisfied.

JSON Processing with jq

Use --json output with jq for advanced filtering and data extraction:

$# Get instance names and statuses
$brev ls --json | jq '.[] | {name, status}'
$
$# Search results as JSON
$brev search --json | jq '.[] | {type, gpu_name, price}'
$
$# Filter search results programmatically
$brev search --json | jq '[.[] | select(.price < 2.0)]'

Real-World Recipes

ML Training Setup

$# Find a cheap A100, create with setup script, and open
$brev search --gpu-name A100 --sort price \
>  | brev create training-box \
>  | brev exec @setup.sh \
>  | brev open cursor

Instance Cleanup

$# Preview stopped instances
$brev ls | awk '/STOPPED/ {print $1}'
$
$# Delete all stopped instances
$brev ls | awk '/STOPPED/ {print $1}' | brev delete
$
$# Stop and delete all test instances
$brev ls | grep "test-" | awk '{print $1}' | brev delete

Quick Dev Session

$# One-liner: create and open in Cursor
$brev create dev-box | brev open cursor

Multi-Node Cluster

$# Create 3 nodes, install deps on all, verify
$brev create my-cluster --count 3 --type g5.xlarge \
>  | brev exec @install-deps.sh \
>  | brev exec "nvidia-smi"