docs: resolve inline review comments on CLI proposal

Drop jsonpath for jq, client-side filter only, note preauth prefix
exists, backfill server cleanup, --list-columns, tags/users list
mockups. Abandoned text struck through, not deleted.

Author: kradalby

docs/proposals/001-cli.md

@@ -7,7 +7,7 @@ The current CLI addresses targets inconsistently: nodes take `--identifier` (ID
 ## Requirements
 
 - `--force` override for all commands requiring prompts
-- `--output` on every command offering `json` (plus a jsonpath expression), drop `yaml` and `json-line`
+- `--output` on every command offering `json` ~~(plus a jsonpath expression)~~, drop `yaml` and `json-line`; extraction is `--output json` piped to `jq`
 - `--help` auto generated for all commands with good documentation
     - usage examples
     - good command enumeration and descriptions
@@ -126,10 +126,13 @@ headscale
 
 Commands that go away:
 
-- `nodes backfillips` — dropped entirely.
-COMMENT: also clean up this logic in the server so we are ridd of it.
+- `nodes backfillips` — dropped entirely, and the server logic goes with it:
+  `State.BackfillNodeIPs` (`state/state.go`), `HSDatabase.BackfillNodeIPs`
+  (`db/ip.go`) and the `/api/v1/node/backfillips` endpoint. IP allocation is
+  guaranteed at registration, so the backfill safety net is dead weight. Remove
+  it in its own commit, separate from the CLI change.
 - `nodes register` — already deprecated, replaced by `auth register`.
-- `configtest` and `dumpConfig` — folded into `config validate`. 
+- `configtest` and `dumpConfig` — folded into `config validate`.
 - `generate private-key` — becomes `config generate-private-key`.
 
 ## Global flags and environment
@@ -189,9 +192,11 @@ Error: "node" matches multiple nodes, use the ID to select one:
 
 Because IDs are checked first, a node that is literally _named_ "12" cannot be selected by name if a node with ID 12 exists — use its ID instead.
 
-Preauth keys are today only addressable by full key or numeric ID. To make `<id or prefix>` work everywhere, keys get a short unique prefix that is shown in listings and can be used as a target.
+~~Preauth keys are today only addressable by full key or numeric ID. To make `<id or prefix>` work everywhere, keys get a short unique prefix that is shown in listings and can be used as a target.~~
 
-Human focused error messages is very valuable here. 
+Preauth keys already carry a `Prefix` (the bcrypt scheme, `PreAuthKey.Prefix`) — the same lookup mechanism as API keys. Nothing new to add to the data model; the work is CLI-side: show the prefix in listings and let the resolver accept it. Legacy plaintext keys created before the bcrypt migration have an empty prefix and stay addressable by ID.
+
+Human focused error messages is very valuable here.
 
 ## More examples
 
@@ -225,8 +230,8 @@ headscale nodes routes set 12 "" # clear the approved set
 headscale nodes routes clear 12 # sugar for `set 12 ""`
 
 # Exit nodes are enabled by setting both 0.0.0.0/0 and ::/0
-# If either IPv4 and IPv6, exit, or exit-node is passed, then 
-# we enable exit nodes. 
+# If either IPv4 and IPv6, exit, or exit-node is passed, then
+# we enable exit nodes.
 headscale nodes routes approve 12 exit
 headscale nodes routes approve 12 exit-node
 headscale nodes routes approve 12 0.0.0.0/0
@@ -247,7 +252,7 @@ Users, auth, policy and oauth2:
 headscale users list
 headscale users delete <name>
 
-# Only available for internal user management. 
+# Only available for internal user management.
 # OIDC managed users causes error.
 headscale users create <name> # optional fields are flags
 headscale users set <name> # optional fields are flags
@@ -282,9 +287,9 @@ headscale api oauth2 delete <id or prefix>
 
 ## Outputs
 
-We will support outputting `json` and a human readable table (jsonpath is layered on top of `json`, see below). Default output mode is always the human readable table. `json` always shows all data. `yaml` and `json-line` are dropped: `json` plus jsonpath covers machine consumption without a third format to document and test.
+We will support outputting `json` and a human readable table ~~(jsonpath is layered on top of `json`, see below)~~. Default output mode is always the human readable table. `json` always shows all data. `yaml` and `json-line` are dropped: ~~`json` plus jsonpath~~ `json` piped to `jq` covers machine consumption without a third format to document and test.
 
-The human readable table is **not a stable interface** — its columns and formatting may change between releases. It already carries ANSI colour and, for list columns, embedded newlines, so it is unstable by construction. Anything scripted should use `--output json`, optionally with a jsonpath expression.
+The human readable table is **not a stable interface** — its columns and formatting may change between releases. It already carries ANSI colour and, for list columns, embedded newlines, so it is unstable by construction. Anything scripted should use `--output json`, piped to `jq` when you need to extract fields.
 
 Columns come in two shapes. Short, fixed-cardinality lists — a node's IP addresses are almost always one v4 and one v6 — render comma-joined on a single line, so rows stay one-per-node. Genuinely variable-length lists such as approved routes may stack one entry per line. Today both render newline-stacked, which produces the noisy alternating rows for IP addresses that we want to avoid.
 
@@ -296,7 +301,20 @@ Currently the table has a fixed set of columns that the user can not change. In
 headscale nodes list --columns id,hostname,online,last-seen
 ```
 
-COMMENT: we need a flag or something to list all the available columns. 
+Because the set is dynamic and type-specific, cobra's static `--help` cannot enumerate it. A `--list-columns` flag prints the available columns for that command and exits; the same list feeds shell completion for `--columns`.
+
+```
+$ headscale nodes list --list-columns
+COLUMN      DESCRIPTION
+id          Node ID
+hostname    Hostname reported by the node
+given-name  Name assigned in headscale
+user        Owning user (or tag)
+ip          Assigned IP addresses
+online      Whether the node is currently connected
+last-seen   Time of last contact
+...
+```
 
 Column names are plain and match the table headers. kubectl uses `HEADER:.json.path` pairs for its `custom-columns`; our types are flat, so we do not need paths. `--filter` uses the same names.
 
@@ -308,21 +326,23 @@ The human readable mode supports a `--filter` flag which allows the user to filt
 
 `--filter-mode` selects how values are matched: `contains` (default), `prefix`, or `fuzzy`. Fuzzy matching is powered by [sahilm/fuzzy](https://github.com/sahilm/fuzzy) — importing fzf's own algorithm package works, but it is an app-internal API and drags fzf's TUI dependencies into go.sum.
 
-kubectl has no client-side filter — its docs point at `jq` and `grep`, and its server-side field selectors are a hardcoded allowlist per resource. Our lists are small, so we filter client side. Whether the list APIs should also grow filter parameters so API users get the same thing is an open question — it needs checking against Tailscale API compatibility.
+kubectl has no client-side filter — its docs point at `jq` and `grep`, and its server-side field selectors are a hardcoded allowlist per resource. Our lists are small, so we filter client side. ~~Whether the list APIs should also grow filter parameters so API users get the same thing is an open question — it needs checking against Tailscale API compatibility.~~ Filtering is client-side only: Tailscale's v2 API — which we model — has no list-filter parameters, so we do not add server-side ones.
 
 The implementation must be generic and work across all CLI commands and types with little faff.
 
-### jsonpath output
+### Extraction with `jq`
+
+~~For JSON output, `--output` also accepts a jsonpath expression:~~
 
-COMMENT: Lets drop this in favour of just recommending `jq` usage. 
+~~kubectl's jsonpath is its own dialect from before the standard existed. We use [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) instead, via [theory/jsonpath](https://github.com/theory/jsonpath) (MIT, actively maintained). That meets the bar of getting it mostly for free: one library wired into the output path, and the expressions are the standard ones documented everywhere.~~
 
-For JSON output, `--output` also accepts a jsonpath expression:
+We do not build a jsonpath dialect into the CLI. `--output json` plus `jq` covers extraction without a dependency or a bespoke expression syntax to document:
 
 ```
-headscale nodes list --output jsonpath='$.nodes[*].name'
+headscale nodes list --output json | jq -r '.nodes[].name'
 ```
 
-kubectl's jsonpath is its own dialect from before the standard existed. We use [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535) instead, via [theory/jsonpath](https://github.com/theory/jsonpath) (MIT, actively maintained). That meets the bar of getting it mostly for free: one library wired into the output path, and the expressions are the standard ones documented everywhere.
+The docs carry a few `jq` recipes for the common cases (names, IPs, filtering by field).
 
 ## Informative feedback
 
@@ -331,7 +351,7 @@ We should focus on success and error messaging that is meaningful to humans.
 For example, if a user sets the expiry of a node 2h30m into the future:
 
 ```
-$ headscale expire set 12 2025-08-27T10:00:00Z
+$ headscale nodes set-expiry 12 2025-08-27T10:00:00Z
 Node 12 (mynode) will now expire in 2h30m (2025-08-27 10:00:00 UTC)
 ```
 
@@ -346,12 +366,32 @@ Deleting something that still has a dependency in the database, lets say deletin
 
 ## Open questions
 
-- Should `--filter` also be implemented server side so API users benefit too, and does that conflict with staying compatible with Tailscale's API?
-COMMENT: Lets not do this for now. Tailscale's V2 API does not support this and that is the API we are modeling after.
-- Preauth keys need a short prefix to be addressable without the full secret — confirm we're happy adding that.
-COMMENT: we already have this? all the keys are based on the same code which uses a prefix for lookup.
-- Should `headscale nodes tags list` show which nodes are associated with each tag?
-COMMENT: Maybe, in that case we have to be smarter, if there are 20+ nodes, it will look really difficult to interpret, so then we should truncate the result somehow.
-In that case we could have a flag to also show nodes to list them all. Then we should have the same for users in a way I think. We need to mock the commands and returning UI for that. 
+- ~~Should `--filter` also be implemented server side so API users benefit too, and does that conflict with staying compatible with Tailscale's API?~~ Resolved: no. Client-side only — Tailscale's v2 API has no list-filter parameters and we model that API.
+- ~~Preauth keys need a short prefix to be addressable without the full secret — confirm we're happy adding that.~~ Resolved: already done. `PreAuthKey.Prefix` exists (bcrypt scheme, same as API keys); only the CLI surfacing (show in listings, accept in the resolver) is outstanding.
+
+### Listing related entities: `tags list` and `users list`
+
+`tags list` and `users list` want to show associated nodes, but a raw dump gets unreadable past a handful. Default to a **count plus a truncated sample**, with `--expand` to show every node. Same pattern for both.
+
+```
+$ headscale nodes tags list
+TAG           NODES  SAMPLE
+tag:server    23     node0, node1, node2 … (+20)
+tag:ci        2      builder0, builder1
+tag:example   0
+
+$ headscale nodes tags list --expand tag:server
+TAG         NODE      USER
+tag:server  node0     kradalby
+tag:server  node1     kradalby
+tag:server  …
+
+$ headscale users list
+ID  NAME      NODES  SAMPLE
+1   kradalby  12     node0, node1, node2 … (+9)
+2   juanfont  3      nodeA, nodeB, nodeC
+```
+
+Open: exact truncation width (fixed N vs terminal-width aware) and whether `--expand` takes an optional target to expand just one row.
 
 [^1]: A tag is easily identifiable because it always starts with `tag:`.