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

29 pointsposted a month ago
by dahlia
(hackers.pub)

8 Comments

fainpul

21 days ago

I have to praise PowerShell here. You get tab completion [0], type checking, automatically generated syntax help text etc. for free, just by writing your CLI tool in PowerShell.

Then you can also use a simple, built-in, declarative DSL to gradually enhance the robustness of your CLI by adding more checks or constraints, or use "parameter sets" [1] to define which parameters can and cannot be used together — tab completion will behave accordingly and suggest only what's allowed.

Dynamic completers, like mentioned in the article, can also be done [2].

[0] https://learn.microsoft.com/en-us/powershell/scripting/learn...

[1] https://learn.microsoft.com/en-us/powershell/module/microsof...

[2] https://learn.microsoft.com/en-us/powershell/module/microsof...

dgunay

22 days ago

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.

queenkjuul

22 days ago

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.

hnlmorg

22 days ago

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.

tiltowait

22 days ago

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).

epage

22 days ago

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.

frabonacci

22 days ago

+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

pvtmert

22 days ago

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.