***

title: Composable Workflows
description: >-
Chain Brev CLI commands together using pipes, batch operations, and structured
output for automation workflows.
--------------------------------

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

```mermaid
%%{init: {'themeVariables': {'fontFamily': 'monospace'}}}%%
flowchart LR
    A["<b>Discovery</b><br />brev search<br />brev ls<br />grep/awk"] --> B["<b>Lifecycle</b><br />brev create<br />brev stop<br />brev start<br />brev delete"]
    B --> C["<b>Access</b><br />brev open<br />brev exec<br />brev shell<br />brev delete"]
    style A text-align:left
    style B text-align:left
    style C text-align:left
```

**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:

| Mode                       | Behavior                                 | Example                |
| -------------------------- | ---------------------------------------- | ---------------------- |
| **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:

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

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

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

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

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

```bash
# Preview what will be stopped
brev ls | awk '/RUNNING/ {print $1}'

# Then actually stop
brev ls | awk '/RUNNING/ {print $1}' | brev stop
```

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

## JSON Processing with jq

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

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

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

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

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

### Multi-Node Cluster

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