Skip to content

docs(skill): document brev ls nodes and the instance/node split #434

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
theFong wants to merge 2 commits into
base: main
Choose a base branch
from
+74 −1
Open

docs(skill): document brev ls nodes and the instance/node split #434

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ed68c3
docs(skill): document `brev ls nodes` and the instance/node split
theFong Jul 31, 2026
6931785
docs(skill): drop trigger keyword additions
theFong Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .agents/skills/brev-cli/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@ brev create my-instance --type g5.xlarge
# List your instances
brev ls

# List external nodes (a separate list from `brev ls`)
brev ls nodes

# SSH into an instance (interactive)
brev shell my-instance

Expand Down Expand Up @@ -169,6 +172,36 @@ brev copy my-instance:/remote/file ./local-path/
brev port-forward my-instance -p 8080:8080
```

### Listing Instances and Nodes
`brev ls` covers two separate namespaces. External nodes never appear in
`brev ls`, so check `brev ls nodes` before concluding a machine doesn't exist.

```bash
brev ls # cloud instances
brev ls instances # same as above, explicit
brev ls nodes # external nodes only (machines registered to the org)
brev ls orgs # organizations
brev ls --json # machine-readable
brev ls nodes --json
```

| | `brev ls` | `brev ls nodes` |
|---|---|---|
| Status values | `RUNNING` / `STOPPED` | `Connected` / `Disconnected` |
| Columns | NAME, STATUS, BUILD, SHELL, ID, MACHINE, GPU | NAME, STATUS |
| `stop` / `start` / `delete` | yes | no — Brev doesn't manage their lifecycle |

The two `--json` shapes differ: `brev ls nodes --json` is a top-level array,
while `brev ls --json` wraps rows in `.workspaces`.

```bash
brev ls nodes --json | jq -r '.[].name'
brev ls --json | jq -r '.workspaces[].name'

# Names of nodes that are currently connected
brev ls nodes --json | jq -r '.[] | select(.status=="Connected") | .name'
```

### Instance Management
```bash
# List instances
Expand Down Expand Up @@ -267,6 +300,7 @@ Do this proactively when:

**"Instance not found":**
- Run `brev ls` to see available instances
- Run `brev ls nodes` — external nodes are a separate list and never show up in `brev ls`
- Check if you're in the correct org: `brev org ls`

**"Failed to create instance":**
Expand Down
41 changes: 40 additions & 1 deletion .agents/skills/brev-cli/reference/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,16 +211,55 @@ brev search cpu | brev create my-cpu-box
List instances in active org.

```bash
brev ls [flags]
brev ls [subcommand] [flags]
```

**Subcommands:**
| Subcommand | Lists |
|---|---|
| *(none)* | cloud instances |
| `instances` | cloud instances (explicit form) |
| `nodes` | external nodes only |
| `orgs` | organizations |

**Flags:**
| Flag | Short | Description |
|------|-------|-------------|
| `--org` | `-o` | Override active org |
| `--all` | | Show all instances in org |
| `--json` | | Output as JSON |

#### Instances vs. external nodes

Two separate namespaces — an external node never appears in `brev ls`.

```bash
$ brev ls
NAME STATUS BUILD SHELL ID MACHINE GPU
my-instance RUNNING COMPLETED READY jmorx0saw n2d-standard-2 -

$ brev ls nodes
NAME STATUS
my-node Connected
```

| | `brev ls` | `brev ls nodes` |
|---|---|---|
| Status values | `RUNNING` / `STOPPED` | `Connected` / `Disconnected` |
| Columns | NAME, STATUS, BUILD, SHELL, ID, MACHINE, GPU | NAME, STATUS |
| `stop` / `start` / `delete` | yes | no |

The two `--json` shapes differ — `brev ls nodes --json` returns a top-level
array, `brev ls --json` wraps rows in `.workspaces`:

```bash
brev ls nodes --json | jq -r '.[].name'
brev ls --json | jq -r '.workspaces[].name'

# Only the nodes that are currently connected
brev ls nodes --json | jq -r '.[] | select(.status=="Connected") | .name'
```

When stdout is piped, outputs instance names only (one per line) for chaining.

### brev delete
Expand Down
Loading