From 7ed68c395255a44347d690c513a1f0de2ac6c145 Mon Sep 17 00:00:00 2001 From: Alec Fong Date: Fri, 31 Jul 2026 16:57:24 +0000 Subject: [PATCH 1/2] docs(skill): document `brev ls nodes` and the instance/node split The brev-cli skill never mentioned `brev ls nodes`, so external nodes were invisible to it. An agent that ran `brev ls`, saw no match, and concluded a machine did not exist would be wrong on any org that registers external nodes. Adds the `brev ls` subcommands (instances / nodes / orgs), a short comparison of the two namespaces, and a troubleshooting pointer under "Instance not found". Also notes that the two --json shapes differ: `ls nodes --json` is a top-level array while `ls --json` wraps rows in .workspaces, so the same jq path cannot serve both. Documentation only; no CLI behaviour changes. --- .agents/skills/brev-cli/SKILL.md | 36 +++++++++++++++- .agents/skills/brev-cli/reference/commands.md | 41 ++++++++++++++++++- 2 files changed, 75 insertions(+), 2 deletions(-) diff --git a/.agents/skills/brev-cli/SKILL.md b/.agents/skills/brev-cli/SKILL.md index cb7b7cc2c..975728dd2 100644 --- a/.agents/skills/brev-cli/SKILL.md +++ b/.agents/skills/brev-cli/SKILL.md @@ -27,7 +27,7 @@ Use this skill when users want to: - Port forward from remote to local - Manage organizations and instances -**Trigger Keywords:** brev, gpu, cpu, instance, create instance, ssh, vram, vcpu, A100, H100, cloud gpu, cloud cpu, remote machine, shell +**Trigger Keywords:** brev, gpu, cpu, instance, create instance, ssh, vram, vcpu, A100, H100, cloud gpu, cloud cpu, remote machine, shell, node, external node, brev ls nodes ## Quick Start @@ -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 @@ -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 @@ -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":** diff --git a/.agents/skills/brev-cli/reference/commands.md b/.agents/skills/brev-cli/reference/commands.md index 978de983b..fe91cbbd5 100644 --- a/.agents/skills/brev-cli/reference/commands.md +++ b/.agents/skills/brev-cli/reference/commands.md @@ -211,9 +211,17 @@ 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 | |------|-------|-------------| @@ -221,6 +229,37 @@ brev ls [flags] | `--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 From 6931785d2c3a2a822961b933556f52fb098170d0 Mon Sep 17 00:00:00 2001 From: Alec Fong Date: Fri, 31 Jul 2026 17:01:10 +0000 Subject: [PATCH 2/2] docs(skill): drop trigger keyword additions Keep the change scoped to documenting brev ls nodes; the existing trigger keyword list is left untouched. --- .agents/skills/brev-cli/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/brev-cli/SKILL.md b/.agents/skills/brev-cli/SKILL.md index 975728dd2..f054e4526 100644 --- a/.agents/skills/brev-cli/SKILL.md +++ b/.agents/skills/brev-cli/SKILL.md @@ -27,7 +27,7 @@ Use this skill when users want to: - Port forward from remote to local - Manage organizations and instances -**Trigger Keywords:** brev, gpu, cpu, instance, create instance, ssh, vram, vcpu, A100, H100, cloud gpu, cloud cpu, remote machine, shell, node, external node, brev ls nodes +**Trigger Keywords:** brev, gpu, cpu, instance, create instance, ssh, vram, vcpu, A100, H100, cloud gpu, cloud cpu, remote machine, shell ## Quick Start