Add `claudebox list` — no way to see your boxes, and none at all to see their snapshots #7

New issue

Closed

opened 2026-07-13 20:23:23 +00:00 by dan-claude-bot · 0 comments

dan-claude-bot commented

2026-07-13 20:23:23 +00:00

(Migrated from github.com)

Problem

There is no claudebox list. The only lister is status, and nothing about it
behaves the way a new user expects.

1. The obvious command doesn't exist — and fails silently.

$ claudebox list
claudebox — trust-less, isolated Incus VMs with Claude Code, creds-free.
  claudebox new --name <box> ...
$ echo $?
0

An unknown command falls through the help|*) arm, so a wrong guess prints the
help and exits 0. Nothing tells you list isn't a command; you're left to
infer it from a wall of help text. (The exit-0-on-typo half of this is tracked
separately in the CLI-contract issue; this issue is about the missing command.)

2. status is misnamed, and its documented signature is a lie.

The CLI's own help says:

claudebox shell|down|start|status|rm <box>

…which reads as status <box> — a per-box status. But the implementation
(bin/claudebox:88) never looks at the
argument:

status)   incus list ${remote:+"$remote"} "user.claudebox=1" ;;

So claudebox status work silently ignores work and prints every box. The
README, meanwhile, documents it correctly as claudebox status # list boxes.
Two docs, two different contracts, and the code matches neither name.

3. You cannot see your snapshots — which the headline workflow requires.

The README's central move is snapshot-then-clone:

claudebox snapshot work authed
claudebox new --name feature --from work/authed

That needs the snapshot label. There is no command that shows you one. Once
you've forgotten whether you called it authed or logged-in, the CLI cannot
help you — you have to drop to incus snapshot list <box> and know that
claudebox instances are plain Incus instances. The tool's own reuse story dead-ends
on missing information.

Proposal

Add a first-class list, and keep status working as a deprecated alias so
nobody's muscle memory (or the README) breaks.

$ claudebox list
NAME       STATE    TYPE  IPV4          SNAPSHOTS
work       RUNNING  VM    10.216.10.42  2
feature    STOPPED  VM    -             0

$ claudebox list work           # detail for one box, including snapshot labels
NAME       work
STATE      RUNNING
TYPE       VM
IPV4       10.216.10.42
CREATED    2026-07-11T09:14:00Z

SNAPSHOTS
  authed        2026-07-11T09:40:12Z
  post-clone    2026-07-12T14:02:55Z

Clone one:  claudebox new --name <new> --from work/authed

Details:

list shows only claudebox-tagged instances (the existing user.claudebox=1
filter), so it never touches unrelated Incus instances on the host.
list <box> closes the snapshot gap: it prints the labels and the exact
--from line to copy, connecting the two halves of the README workflow.
A friendly empty state (no boxes yet — claudebox new --name work) instead of
a bare header.
--json for scripting, --remote honored as elsewhere.
Unknown box → a real error on stderr with a nonzero exit, not empty output.
status prints a one-line deprecation note to stderr and forwards to list.
README updated so status's replacement is documented.

No new dependencies: this is incus list / incus snapshot list with
--format csv behind an awk formatter.

## Problem There is no `claudebox list`. The only lister is `status`, and nothing about it behaves the way a new user expects. **1. The obvious command doesn't exist — and fails silently.** ```console $ claudebox list claudebox — trust-less, isolated Incus VMs with Claude Code, creds-free. claudebox new --name <box> ... $ echo $? 0 ``` An unknown command falls through the `help|*)` arm, so a wrong guess prints the help and **exits 0**. Nothing tells you `list` isn't a command; you're left to infer it from a wall of help text. (The exit-0-on-typo half of this is tracked separately in the CLI-contract issue; this issue is about the missing command.) **2. `status` is misnamed, and its documented signature is a lie.** The CLI's own help says: ``` claudebox shell|down|start|status|rm <box> ``` …which reads as `status <box>` — a per-box status. But the implementation ([`bin/claudebox:88`](../blob/main/bin/claudebox#L88)) never looks at the argument: ```sh status) incus list ${remote:+"$remote"} "user.claudebox=1" ;; ``` So `claudebox status work` silently ignores `work` and prints *every* box. The README, meanwhile, documents it correctly as `claudebox status # list boxes`. Two docs, two different contracts, and the code matches neither name. **3. You cannot see your snapshots — which the headline workflow requires.** The README's central move is snapshot-then-clone: ```sh claudebox snapshot work authed claudebox new --name feature --from work/authed ``` That needs the snapshot *label*. There is no command that shows you one. Once you've forgotten whether you called it `authed` or `logged-in`, the CLI cannot help you — you have to drop to `incus snapshot list <box>` and know that claudebox instances are plain Incus instances. The tool's own reuse story dead-ends on missing information. ## Proposal Add a first-class `list`, and keep `status` working as a deprecated alias so nobody's muscle memory (or the README) breaks. ```console $ claudebox list NAME STATE TYPE IPV4 SNAPSHOTS work RUNNING VM 10.216.10.42 2 feature STOPPED VM - 0 $ claudebox list work # detail for one box, including snapshot labels NAME work STATE RUNNING TYPE VM IPV4 10.216.10.42 CREATED 2026-07-11T09:14:00Z SNAPSHOTS authed 2026-07-11T09:40:12Z post-clone 2026-07-12T14:02:55Z Clone one: claudebox new --name <new> --from work/authed ``` Details: - `list` shows only claudebox-tagged instances (the existing `user.claudebox=1` filter), so it never touches unrelated Incus instances on the host. - `list <box>` closes the snapshot gap: it prints the labels **and** the exact `--from` line to copy, connecting the two halves of the README workflow. - A friendly empty state (`no boxes yet — claudebox new --name work`) instead of a bare header. - `--json` for scripting, `--remote` honored as elsewhere. - Unknown box → a real error on stderr with a nonzero exit, not empty output. - `status` prints a one-line deprecation note to stderr and forwards to `list`. - README updated so `status`'s replacement is documented. No new dependencies: this is `incus list` / `incus snapshot list` with `--format csv` behind an `awk` formatter.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/box#7

No description provided.

Add claudebox list — no way to see your boxes, and none at all to see their snapshots #7

Problem

Proposal

Add `claudebox list` — no way to see your boxes, and none at all to see their snapshots #7