Add completion spec: Talos Linux CLI (talosctl)

[maxmilian]

Closes #293 (tracks warpdotdev/warp#12693)

Adds a completion spec for talosctl, the Talos Linux CLI for out-of-band management of Kubernetes nodes.

What's included

• json/talosctl.json — static spec walked from talosctl v1.13.6's Cobra command tree (106 nodes, 49 top-level commands), covering all subcommands, flags, and positional args, with filepaths/folders templates on path-like flags (--talosconfig, --file, --*-path, --*-dir, …).
• src/generators/talosctl.rs — a single talosctl_builtin_completion generator that delegates dynamic completions to the CLI's hidden Cobra __complete command, mirroring oc_builtin_completion in oc.rs. It powers:
  • config context / config remove context names (offline, from talosconfig)
  • --context flag values
  • cluster-backed completions (service/logs/restart service IDs, get/edit/patch resource types, --nodes/--endpoints values), same connected-cluster assumption as the kubectl/oc specs
• Cobra __complete emits value<TAB>description pairs, so the post-process splits on tab and surfaces descriptions in the menu. 3 unit tests cover plain values, descriptions, and error filtering.

Verification

• script/presubmit green (fmt, clippy, full test suite incl. spec-deserialization invariants)
• End-to-end in a local Warp build against this branch:

Static subcommand completions (talosctl + Tab):

Dynamic contexts via talosctl_builtin_completion (talosctl config context + Tab, three contexts defined in a local talosconfig):

Notes for reviewers

• The spec is machine-walked from the CLI's own --help/__complete output, then hand-curated — regeneration for future talosctl versions is reproducible.
• --nodes/--endpoints completion via __complete can be slow when the configured cluster is unreachable (talosctl attempts discovery). This matches the CLI's native shell completion behavior and the connected-cluster assumption of the existing kubectl/oc generators, but happy to drop those two attachment points if you'd prefer offline-only generators.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XWwajmLbgJbK6JBCY8nKfk

[warp-for-oss]

@maxmilian

Every PR must be linked to a same-repo issue before Oz can review it.

This PR is linked to #293, but no linked issue is marked ready-to-implement yet. Only repository maintainers apply that label, so please wait for a maintainer to mark the issue. Once it is marked, push a new commit or comment /oz-review to re-trigger review.

Powered by Oz

[warp-for-oss]

@maxmilian

Every PR must be linked to a same-repo issue before Oz can review it.

This PR is linked to #293, but no linked issue is marked ready-to-implement yet. Only repository maintainers apply that label, so please wait for a maintainer to mark the issue. Once it is marked, push a new commit or comment /oz-review to re-trigger review.

Powered by Oz

[warp-factories]

A factory review pass was requested on this PR. Reviewing the current revision (a599dd5) now; findings will follow in a single review.

Responding as Warp for OSS: Open session · View in factory

[warp-factories]

Overview

Adds a 106-node static talosctl completion tree plus a Cobra __complete-backed dynamic generator, following the existing oc/kubectl pattern; the generator is correctly registered and the spec parses cleanly. One spec gap is worth fixing; this review is advisory and merge remains a maintainer decision.

Concerns

• config add --ca, --crt, and --key are documented as paths but modeled as bare "name": "string" with no template, so Warp offers no file completion for them. Add "template": "filepaths" to those three and audit the remaining explicitly file- or directory-valued arguments.
• The generator joins raw tokens into a shell string, so shell metacharacters in the partial command line are re-parsed by the shell rather than passed through to talosctl __complete. This is inherited verbatim from oc.rs:67, kubectl.rs:288, and yc.rs:33 on main, and CommandBuilder exposes no argv-based API to avoid it — flagged for maintainer awareness, not as this PR's job.
• The description asks whether --nodes/--endpoints should keep their __complete attachment points given they can hang against an unreachable cluster. That matches the kubectl/oc precedent, so it needs a maintainer's call rather than a change here.

Verdict

Checks: build unexamined (no Rust toolchain available in the review environment), tests unexamined (same), CI green but thin — verification/cla-signed is the only check running on this PR, so the author's script/presubmit claim is unverified, visual proof present (both screenshots load and show static and dynamic completions)

Found: 0 critical, 1 important, 1 suggestion, 0 nits

Responding as Warp for OSS: Open session · View in factory

[warp-factories]

important — --ca, --crt, and --key are each documented as "the path to …" but declared as bare strings, so Warp cannot complete filenames for them. Add "template": "filepaths" to each of the three argument objects, matching how --talosconfig is declared above.

[maxmilian]

Fixed in 5dcebba, and thanks — this was worth catching, because the gap was wider than these three flags.

Rather than patch only config add, I audited every option in the spec whose description names a path, file or directory. Seventeen were declared as bare "string":

filepaths — config add --ca/--crt/--key, gen crt --ca/--csr, gen csr --key, gen config --with-secrets, gen secureboot database --enrolled-certificate/--signing-certificate/--signing-key, validate --config, rotate-ca --output, support --output, pcap --output

folders — gen secrets --from-kubernetes-pki ("a Kubernetes PKI directory"), gen secureboot --output ("path to the directory storing the generated files"), cluster --state ("directory path to store cluster state")

This matches how --talosconfig and --output-file were already declared in this same spec.

Six candidates surfaced by the audit that I deliberately left alone:

• --config-patch / --patch (on apply-config, gen config, machineconfig patch, cluster create dev/docker/qemu) — the value is either an inline JSON/YAML patch or a @file reference, so it isn't a plain path.
• gen config --output — "when multiple output types are specified, it must be a directory", so neither filepaths nor folders is correct for every invocation. Happy to pick one if you have a preference for how ambiguous cases are handled here.
• gen crt --name / gen key --name — a basename, not a path.
• list --type, logs --tail, image cache-create --layout — matched my "path" grep on wording only; they're a filter, a line count and an enum.

Verified with script/presubmit on the new head: prettier --check clean, cargo fmt --check clean, cargo clippy -- -D warnings clean, cargo test 79 passed (which includes the invariant that every spec deserializes and every referenced generator exists).

[warp-factories]

suggestion — Joining the raw tokens produces a shell string, so metacharacters already typed on the command line get re-parsed by the shell instead of reaching talosctl __complete as literal arguments. This is identical to oc.rs:67 and kubectl.rs:288 on main and CommandBuilder offers no argv-based alternative, so nothing to change here — noting it for maintainers as a shared-generator concern.

[maxmilian]

Agreed on the analysis, and I've left it as-is — you flagged this for maintainer awareness rather than as this PR's job, and I think that's the right call.

To confirm your reading: the shape is inherited verbatim from the existing generators (oc.rs:67, kubectl.rs:288, yc.rs:33), and CommandBuilder has no argv-based API to switch to, so fixing it properly means changing that shared surface rather than this one spec. Doing that here would put a cross-cutting behaviour change inside a PR that is otherwise a new completion spec.

Same for --nodes / --endpoints keeping the __complete hook: it can hang when the cluster is unreachable, but that matches the kubectl/oc precedent, so changing it is a product decision about how these generators should behave rather than something specific to talosctl.

Happy to open a follow-up for the argv issue across all four generators if that's useful — just say the word.

[warp-factories]

This repo has no CODEOWNERS or STAKEHOLDERS file, so I could not resolve an owner for the changed paths and did not request a reviewer rather than guess one. @vikvang — handing routing back to you; the review above is advisory and merge stays a maintainer decision.

Responding as Warp for OSS: Open session · View in factory

[maxmilian]

@vikvang — thanks for putting this through a factory review pass; that unblocked real feedback after the PR had been sitting a while.

The important finding is fixed in 5dcebba. It pointed at three flags on config add, but the same gap ran through the spec, so I audited every option whose description names a path and declared templates on all seventeen — filepaths for file-valued ones, folders for the three directory-valued ones. Six ambiguous candidates I deliberately left alone, with reasoning in the thread. The suggestion about CommandBuilder I left untouched, since the bot noted it's inherited from oc.rs / kubectl.rs / yc.rs and is a shared-surface decision rather than this PR's job — happy to open a follow-up for it if that's wanted.

script/presubmit is clean on the new head: prettier, cargo fmt, cargo clippy -- -D warnings, and cargo test (79 passed).

One thing still parked, if you're the right person to ask: Oz's CHANGES_REQUESTED from 07-16 is waiting on the linked issue #293 carrying ready-to-implement, and #293 currently only has enhancement. That check is the one remaining gate on this PR and it isn't something I can clear from my side. No urgency — just flagging it since the factory pass has otherwise brought this current.

[maxmilian]

Pushed 83ae1dd — a spec fix I found while re-auditing this branch against main.

talosctl usage was transcribed straight from its usage line, [path1] [path2] ... [pathN], and the ellipsis survived curation as a fourth argument with an empty name:

"args": [
    { "name": "path1", "isOptional": true },
    { "name": "path2", "isOptional": true },
    { "name": "", "isVariadic": true },
    { "name": "pathN", "isOptional": true }
]

So Warp stopped completing after four positionals and offered an unnamed slot in the middle. The command takes an arbitrary number of node paths, so it is one optional variadic argument — the same modelling the multi-arg audit in #342–#345 applied to the other specs. No template, deliberately: these are paths on the remote node rather than local ones, which is why copy's src-path is untemplated while its local-path carries filepaths.

I swept the rest of the spec for that artifact class programmatically — no options with args as an array, no other empty-named arguments, no leftover ellipses, and no icon fields left behind by #388. This was the only instance.

Two things I checked while I was in here, in case they save a reviewer time:

• The branch rebases cleanly onto d69b340 and passes the full presubmit there (179 tests), so the Fig generator port in Port Fig generators to Rust #391/Port Fig postProcess, token-aware generators, and filters #392 and the icon strip in Strip unused Fig JSON icon fields from command signatures #388 don't disturb it. I've left the base alone so the review threads above stay anchored, but it can be rebased on request.
• On the open suggestion thread about joining raw tokens into a shell string: I re-checked after the token-aware generator work in Port Fig postProcess, token-aware generators, and filters #392, and CommandBuilder still has no argv-based constructor — eleven generators, oc/kubectl/yc included, still build the command this way. So that stays a cross-cutting change rather than this PR's, as the review noted. Happy to open a follow-up for it.

Presubmit on this branch is green: prettier --check, cargo fmt --check, clippy -D warnings, 79 tests.

On process, purely so it isn't a mystery: the only outstanding review here is the automated one from the day this opened, asking that the linked issue #293 be marked ready-to-implement. That label is maintainer-only and #293 hasn't been triaged since, so there's nothing I can do from this side to clear it. The upstream request, warpdotdev/warp#12693, does carry ready-to-implement. No urgency — flagging it so the red X isn't read as unaddressed feedback.