docs(skill): document brev ls nodes and the instance/node split - #434
Open
theFong wants to merge 2 commits into
Open
docs(skill): document brev ls nodes and the instance/node split#434theFong wants to merge 2 commits into
brev ls nodes and the instance/node split#434theFong wants to merge 2 commits into
Conversation
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.
Keep the change scoped to documenting brev ls nodes; the existing trigger keyword list is left untouched.
Contributor
|
might be worth including information about |
patelspratik
approved these changes
Jul 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The
brev-cliagent skill never mentionedbrev ls nodes, so external nodes were effectively invisible to it. An agent that ranbrev ls, saw no match, and concluded a machine didn't exist would be wrong on any org that registers external nodes — the two are separate namespaces and a node never appears inbrev ls.What changed
Documentation only, no CLI behaviour changes.
.agents/skills/brev-cli/SKILL.mdbrev ls nodesin Quick Startinstances/nodes/orgssubcommands, with a table contrasting the two namespaces (status vocabulary, columns, whetherstop/start/deleteapply)brev ls nodes.agents/skills/brev-cli/reference/commands.mdbrev lsentry expanded with the subcommand table and side-by-side output samplesThe
--jsonshape differenceBoth files call out something that's easy to trip over when scripting: the two
--jsonoutputs have different shapes, so the samejqpath can't serve both.Using the wrong one fails with
Cannot index array with string "name".Verification
Every command shown was run against a live org on
v0.6.329.