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.
+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
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.
All shells do. Even alternate shells like Murex and Nushell.
The problem isn’t that they can’t, it’s that writing context aware shell completions is hard because every tool does things slightly differently, and typically completions are not done by the same people who wrote the CLI tool to begin with.
So you end up with a thousand edge cases where stuff isn’t 100% correct.
fish is a bit insonsistent on it. For instance, `git add <tab>` will only autocomplete for modified files. It will also fill in wildcards, e.g. `cat *.txt <tab>` will expand to show all .txt files. On the failure side, `rm foo <tab>` will still show `foo` as an option.
IME, zsh has better autocompletion (which, at the time at least, was a separate install).
- completions being aware of previous options, flags, and values
A lot of completions have the first. Some have the second. The last is rare. The completer needs knowledge of when flags, options, and value can be repeated and change which future options and values are suggested.
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.
+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
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.
All shells do. Even alternate shells like Murex and Nushell.
The problem isn’t that they can’t, it’s that writing context aware shell completions is hard because every tool does things slightly differently, and typically completions are not done by the same people who wrote the CLI tool to begin with.
So you end up with a thousand edge cases where stuff isn’t 100% correct.
fish is a bit insonsistent on it. For instance, `git add <tab>` will only autocomplete for modified files. It will also fill in wildcards, e.g. `cat *.txt <tab>` will expand to show all .txt files. On the failure side, `rm foo <tab>` will still show `foo` as an option.
IME, zsh has better autocompletion (which, at the time at least, was a separate install).
There are a couple differen things going on
- completions being aware of the subcommand
- dynamic look ups for specific values
- completions being aware of previous options, flags, and values
A lot of completions have the first. Some have the second. The last is rare. The completer needs knowledge of when flags, options, and value can be repeated and change which future options and values are suggested.