docs: add CLI redesign proposal

Author: kradalby

docs/proposals/001-cli.md

@@ -0,0 +1,293 @@
+# Headscale CLI redesign
+
+**Status:** draft, for discussion. This PR exists so we can shape the design together — it is not meant to be merged as-is.
+
+The CLI has grown organically and it shows. Targets are addressed inconsistently: nodes take `--identifier` (ID only), users take `--identifier` or `--name`, API keys take `--id` or `--prefix`. Positional arguments are used in some places (`nodes rename NEW_NAME` takes the _new_ name positionally, but the target node via a flag) and flags in others. `nodes register` is deprecated in favour of `auth register` but still present. Tables have a fixed set of columns. This proposal is a ground-up restructure of the command tree and its conventions.
+
+## Requirements
+
+- `--force` override for all commands requiring prompts
+- `--output` on every command offering `json`, `json-line` / `jsonl`, drop `yaml`
+- `--help` auto generated for all commands with good documentation
+    - usage examples
+    - good command enumeration and descriptions
+    - the full nested command tree must be presented so people can find commands
+- Any irreversible command should ask for confirm (or `--force`): `delete`, `expire`, `reject`
+- In principle, the entire API should be covered by the CLI. Any operation that can be done with the API should be available. Each entity in Headscale should have CRUD where it makes sense.
+
+## Current root
+
+```
+❯ headscale --help
+
+headscale is an open source implementation of the Tailscale control server
+
+https://github.com/juanfont/headscale
+
+Usage:
+  headscale [command]
+
+Available Commands:
+  apikeys     Handle the Api keys in Headscale
+  auth        Manage node authentication and approval
+  completion  Generate the autocompletion script for the specified shell
+  configtest  Test the configuration.
+  debug       debug and testing commands
+  generate    Generate commands
+  health      Check the health of the Headscale server
+  help        Help about any command
+  mockoidc    Runs a mock OIDC server for testing
+  nodes       Manage the nodes of Headscale
+  policy      Manage the Headscale ACL Policy
+  preauthkeys Handle the preauthkeys in Headscale
+  serve       Launches the headscale server
+  users       Manage the users of Headscale
+  version     Print the version.
+```
+
+## New structure
+
+```
+headscale
+  serve
+  version
+  config
+    validate
+    generate-private-key
+
+  # `auth` is the authentication of nodes to headscale
+  auth
+    # resource
+    key      # preauthkey management
+
+    # actions
+    approve  # approve a pending authentication request
+    reject   # reject a pending authentication request
+    register # register a node via web auth
+
+  # `api` is the authentication towards headscale
+  api
+    key      # api key management
+    oauth2   # oauth2 client management
+
+  # These are resources-ish
+  nodes
+  users
+  policy
+    check
+    get
+    set
+
+  debug
+    health
+    create-node
+    mockoidc
+```
+
+Commands that go away:
+
+- `nodes backfillips` — dropped entirely.
+- `nodes register` — already deprecated, replaced by `auth register`.
+- `configtest` and `dumpConfig` — folded into `config validate`.
+- `generate private-key` — becomes `config generate-private-key`.
+
+## Positional targets
+
+The "primary" object/target should be a positional argument. When a command targets something, the argument comes after the operation and resolves to the target. Flags are for additional and optional things like output format or filtering.
+
+For example, renaming a node:
+
+```
+$ headscale nodes rename <target node identifier> new-hostname
+
+# Using Node ID to resolve the node
+$ headscale nodes rename 42 new-hostname
+
+# Using Node name to resolve the node
+$ headscale nodes rename old-hostname new-hostname
+```
+
+All list arguments are comma separated lists.
+
+## Resolvers
+
+Every type that can be addressed in multiple ways gets a resolver that always resolves to exactly one target, or errors. A resolver never guesses: zero matches is an error, more than one match is an error listing the candidates so the user can retry with the ID.
+
+The resolver checks identifiers in a fixed order, most specific first:
+
+1. Is it an ID and does it resolve? → return that target.
+1. Is it a name (or the other supported fields below) and does it resolve?
+    1. Resolves to one target → return it.
+    1. Resolves to multiple → error with the list of candidates.
+1. Nothing matched → "not found" error.
+
+It should not support every field, but a small, predictable set per type:
+
+| Type                        | Accepted identifiers                        |
+| --------------------------- | ------------------------------------------- |
+| Node                        | ID, hostname, given name                    |
+| User                        | ID, email, username, OIDC unique identifier |
+| Keys (preauth, api, oauth2) | ID, key prefix                              |
+
+Ambiguity looks like this:
+
+```
+$ headscale nodes delete node
+Error: "node" matches multiple nodes, use the ID to select one:
+
+  ID | Hostname | User
+  12 | node     | kradalby
+  13 | node     | juanfont
+```
+
+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. This is the price of never guessing, and IDs-first keeps scripts stable.
+
+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 can be shown in listings and used as a target, so nobody has to paste a full secret into their shell history.
+
+## More examples
+
+```
+# headscale has a node named "mynode" with ID 12.
+
+headscale nodes delete mynode # prompts for confirmation
+headscale nodes delete 12 --force # skips confirmation
+
+headscale nodes tags 12 tag:test,tag:example
+
+headscale nodes set-expiry 12 2025-08-27T10:00:00Z # support more formats
+headscale nodes set-expiry 12 now
+headscale nodes expire 12 # same as set-expiry now
+headscale nodes disable-expiry 12
+```
+
+An alternative shape is a top-level `expire` group instead of `nodes set-expiry`. We want reviewer input on which to pick:
+
+```
+headscale expire set <node id> <expiry time>
+headscale expire set 12 2025-08-27T10:00:00Z # support more formats
+headscale expire set 12 30m
+headscale expire set 12 now
+headscale expire now 12 # same as set now
+headscale expire set 12 never # same as disable
+headscale expire disable 12
+```
+
+The same question applies to routes and tags — top-level groups, or under `nodes`:
+
+```
+headscale routes list # lists all
+headscale routes list 12
+headscale routes approve <node id> <route list>
+headscale routes approve 12 10.0.0.0/8,192.168.0.0/24
+headscale routes approve 12 "" # remove all from 12
+headscale routes disapprove-all 12 # remove all from 12
+
+headscale tags list # list all tags, show node associated with tag?
+headscale tags list <node id> # list tags of node
+headscale tags set <node id> <tag list>
+headscale tags set 12 tag:example,tag:test
+```
+
+Users, auth, policy and oauth2:
+
+```
+headscale users list
+headscale users create <name> # optional fields are flags
+headscale users set <name> # optional fields are flags
+headscale users rename <old-name> <new-name>
+headscale users delete <name>
+
+headscale auth approve <id or prefix>
+headscale auth register <id or prefix> <user>
+headscale auth reject <id or prefix>
+
+headscale auth key list # list all auth keys
+headscale auth key create <user or tag> # [^1], optionals are flags
+headscale auth key revoke <id or prefix>
+headscale auth key delete <id or prefix>
+
+headscale policy check # reads from database or file path from config
+headscale policy check <file path>
+headscale policy get
+headscale policy set <file path>
+
+headscale api oauth list # list all oauth clients
+headscale api oauth create <scope list> <tag list>
+headscale api oauth create devices:core,devices:routes tag:example
+headscale api oauth create devices:core:read tag:example -d "description"
+headscale api oauth revoke <id or prefix>
+headscale api oauth delete <id or prefix>
+```
+
+## Outputs
+
+We will support outputting `json`, `json-line` and a human readable table. Default output mode is always the human readable table. `json` formats will always show all data. `yaml` is dropped.
+
+We looked at `kubectl` as prior art for the sections below. Worth knowing: kubectl's default table columns are decided _server side_ (the API server returns a rendered table), while `custom-columns`, `jsonpath` and `--sort-by` are all applied client side over the full objects. Headscale's lists are small, so everything below is client side; the CLI fetches full objects and formats locally.
+
+### Dynamic table `--columns`
+
+Currently the table has a fixed set of columns that the user can not change. In the new version, the table is configurable and renders only the requested columns. There is a default selection if no `--columns` argument is passed, so the default behaviour stays more or less as today.
+
+```
+headscale nodes list --columns id,hostname,online,last-seen
+```
+
+Column names are simple, stable identifiers matching the table headers — no `HEADER:.json.path` pairs like kubectl's `custom-columns`. Headscale's entities are flat enough that paths add faff without value. The same names are used by `--filter`, so learning one vocabulary covers both.
+
+The implementation must be generic and work across all CLI commands and types with little faff: one table renderer, each type declaring its columns (name, default on/off, how to render the value) once.
+
+### Filtering `--filter`
+
+The human readable mode supports a `--filter` flag which filters rows out of the table before it is rendered. The filter uses the same names as the columns, for example `--filter=hostname:node0`, returning all nodes with `node0` in their hostname. Multiple arguments are allowed and filtered from left to right: `--filter=hostname:node,online:true`.
+
+Matching modes are selected with `--filter-mode`:
+
+- `contains` (default) — substring match, as in the examples above
+- `prefix` — match from the start of the value
+- `fuzzy` — fzf-style fuzzy matching, powered by [sahilm/fuzzy](https://github.com/sahilm/fuzzy) (stdlib-only, MIT; importing fzf's own algorithm package works but it is an app-internal API that drags fzf's TUI dependencies into go.sum)
+
+For what it's worth, kubectl has no client-side row filter at all — its docs tell you to pipe to `jq` or `grep`, and its server-side field selectors are a hardcoded allowlist per resource. We are deliberately filling that gap, because it is cheap for us and useful daily.
+
+Filtering is client side for now. Whether the list APIs should grow filter parameters so API users get the same capability is an open question — it would need checking against Tailscale API compatibility.
+
+### jsonpath output
+
+For extracting values from JSON output, `--output` accepts a jsonpath mode, kubectl-style:
+
+```
+headscale nodes list --output jsonpath='$.nodes[*].name'
+```
+
+Unlike kubectl — whose dialect predates the standard and is implemented in its own template engine (`{range}`/`{end}` and friends) — we use [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535), the standardised JSONPath, via [theory/jsonpath](https://github.com/theory/jsonpath) (MIT, actively maintained, full RFC compliance). This meets the bar of getting it "mostly for free" from a library: expressions users write are the standard ones documented everywhere, and the maintenance cost on our side is wiring one library into the output path.
+
+The implementation must be generic and work across all CLI commands: jsonpath applies to the same JSON the `json` output mode produces.
+
+## Informative feedback
+
+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
+Node 12 (mynode) will now expire in 2h30m (2025-08-27 10:00:00 UTC)
+```
+
+Commands which require confirmation should include all the information the user needs to make the correct decision:
+
+```
+$ headscale nodes delete 12
+Are you sure you want to delete Node 12 (mynode), owned by kradalby? [y/N]
+```
+
+Errors follow the same rule — say what was looked up, what was found, and what to do about it (see the resolver ambiguity example above).
+
+## Open questions
+
+- `expire`, `routes`, `tags`: top-level command groups or subcommands under `nodes`?
+- Should `--filter` also be implemented server side so API users benefit too, and does that conflict with staying compatible with Tailscale's API?
+- Preauth keys need a short prefix to be addressable without the full secret — confirm we're happy adding that.
+- Should `headscale tags list` show which nodes are associated with each tag?
+
+[^1]: A preauth key is owned by either a user or a tag, never both, matching how nodes are owned.