CLI UX consistency sweep against live APISIX

[shreemaan-abhishek]

Mirror the pattern from a7 issues #35, #36, #37, #42, #49: scan every command for doc-vs-code flag mismatches, silently-dropped positional args, inconsistent --output defaults, and confusing --id semantics.

Track findings as discrete sub-issues as they are discovered during the manual smoke walkthrough.

Part of #33

[shreemaan-abhishek]

Sweep results — 10 open UX findings

Manual --help sweep across every <resource> <action> combination plus the Run 1 walkthrough (#34) surfaced 14 UX findings under the four classes this issue asks about. 4 were fixed in PR #51 (BUG-1/2/3/5); the remaining 10 are catalogued below for follow-up.

Full sweep doc lands in PR #52 as docs/ga-ux-sweep.md.

Class 1 — PRD drift (4 findings, PRD-side fix)

1. UX-1 — PRD documents a6 consumer credential <verb> (nested); actual is top-level a6 credential <verb>. Pick one: update PRD, or rename the implementation.
2. UX-2 — PRD lists a6 ssl upload; no upload subcommand exists. SSL has only create/delete/export/get/list/update.
3. UX-3 — PRD lists a6 schema get; no schema top-level command exists at all.
4. UX-4 — PRD says --verbose / -v; the -v shorthand isn't wired up on any command.

Class 2 — Silent unknown subcommand (1 finding, centralised code fix)

5. UX-5/6 — a6 <resource> <typo> (e.g. a6 route deletex --force) returns exit=0 and prints <resource> --help. Typos succeed silently — scripts can't detect the failure. Fix is centralised in pkg/cmd/root (tighten Cobra's unknown-subcommand handling so it errors and exits non-zero).

Class 3 — --output table not supported on single-resource gets (1 class)

6. BUG-6 (from PR fix: GA readiness Run 1 against APISIX 3.16 (#34) #51) — <resource> get -o table returns unsupported output format: table for all 12 single-resource gets, even though <resource> list -o table works. Same gap on create/update. Fix needs a shared per-resource table renderer lifted out of each list.go. PR fix: GA readiness Run 1 against APISIX 3.16 (#34) #51 deferred this; no separate issue exists yet, this should be one.

Class 4 — --id semantics (1 open finding)

7. Global-rule body-id mismatch — a6 global-rule create -f file.yaml with id: foo but plugin key bar is silently accepted by a6; APISIX then forces the id to equal the plugin key, ignoring the file's id:. a7 logged the same shape and treated it as a real bug. Should reject the mismatch up front (mirror the secret create BUG-4 fix shape from PR fix: GA readiness Run 1 against APISIX 3.16 (#34) #51).

Class 5 — Other UX inconsistencies (3 findings)

8. UX-7 — <resource> delete <id> (no --force) silently deletes in non-TTY. PRD says destructive ops "must require confirmation unless --force." Either the PRD allows this carve-out or the CLI should bail out asking for --force when stdin isn't a TTY.
9. UX-8 — a6 config sync --dry-run produces output identical to a6 config diff. A Dry-run — no changes applied. banner would distinguish them.
10. UX-9 — a6 config diff emits a line per known section even when empty (consumer_groups: create=0 update=0 delete=0 unchanged=0 etc.). Collapse zero-change sections by default with a --verbose opt-in.

Disposition

Class	Open count	Type
1 — PRD drift	4	PRD-side decisions (no code yet)
2 — Silent typo	1	Centralised Cobra config
3 — --output table	1 (BUG-6)	12-file refactor + shared renderer
4 — --id body-mismatch	1 (global-rule)	Single-file fix (mirror BUG-4 shape)
5 — Other UX	3	Per-fix, small

Already closed by PR #51: BUG-1 (upstream health 3.x shape), BUG-2 (A6_CONTROL_URL env), BUG-3 (credential delete id echo), BUG-5 (config validate unknown sections).

When picking up #41 follow-up work, each numbered finding above can either become a discrete sub-issue or be bundled (e.g. UX-1..4 as one PRD-cleanup PR; UX-8 + UX-9 as one config-output PR).