CLI's completion should know what options you've typed

+1 to this. I’ve seen the same thing - once completion respects earlier flags, defaults matter less and the CLI becomes self-discoverable. Fish gets part of the way there, but having it modeled at the parser level feels like the missing piece

I have a small tool to manage agents, and one thing it does is let you select an --agent [codex|opencode|etc] and a --model. Valid --model values are specific to the agent though, and some agents like opencode support a huge amount of models.

When I added tab completion for --model that accounts for what --agent is set to, it made it 100x easier to use and I stopped relying on the defaults so much.

It's such a small thing but makes a big difference for discoverability.

shell completions consist of basically a state, and DAG (directed acyclic graph)

consider following

- git -> [ -C, <sub-commands> ]

- <sub-commands> -> [ add, branch, checkout, clone, remote, stash ]

- -C -> [ <directories> ]

- add -> [ <files>, <directories ]

...

- checkout -> [ <refs>, <files>, <directories> ]

---

obviously you could dump all these at every <tab> invocation, i usually create base+completions script considering completions for the base.

this way, i have tools & tools-completion, tools have sub-commands of fix, restart, connect, review, retrieve, etc.

each of these also have completions, like tools-restart-completions. those lists available services/daemons only

while installing, you only need to install "tools completions", that handles the redirect(s) to sub-commands and their sub-commands, making things easier to maintain, simple to operate, and independent.

I think fish does this? I know it gives me branch names as completion options sometimes, idk how aware it is of the specific flags.