A collection of concise write-ups on small things I learn day to day. Zola 2026-09-29T00:00:00+00:00 https://til.hanlho.com/topics/fish/atom.xml 2026-09-29T00:00:00+00:00 2026-09-29T00:00:00+00:00 Hans L'Hoest https://til.hanlho.com/fish/fish-shell-completion-for-custom-commands/ <p>Any custom CLI tool can get tab completion if the tool supports getting its CLI arguments from itself.</p> <p>Example: a small profile wrapper (<code>agentic &lt;profile&gt;</code>) that reads its profiles from <code>~/.config/agentic/profiles.yaml</code>. (I created it to start agents with specific models, settings or system prompts.)</p> <pre data-lang="fish" style="background-color:#2b303b;color:#c0c5ce;" class="language-fish "><code class="language-fish" data-lang="fish"><span style="color:#65737e;"># ~/.config/fish/completions/agentic.fish </span><span style="color:#bf616a;">complete -c </span><span>agentic </span><span style="color:#bf616a;">-f -a </span><span>&quot;</span><span style="color:#a3be8c;">(agentic --list-profiles)</span><span>&quot; </span></code></pre> <ul> <li><code>complete -c &lt;command&gt;</code> registers a completion rule for that command.</li> <li><code>-f</code> disables file completion, so TAB never falls back to completing filenames.</li> <li><code>-a "(...)"</code> is a command substitution: fish runs it on every TAB press and uses the output lines as candidates.</li> </ul> <p>Three things make the rest automatic:</p> <ol> <li> <p><strong>Fish autoloads completions.</strong> Any file at <code>~/.config/fish/completions/&lt;command&gt;.fish</code> is sourced lazily the first time completion for <code>&lt;command&gt;</code> is requested.</p> </li> <li> <p><strong>The TAB-as-description convention.</strong> When a candidate contains a TAB character, fish renders the part before the tab as the completion and the part after it as the grey description on the right. So the wrapper prints <code>name&lt;TAB&gt;description</code> (<code>printf '%s\t%s\n'</code>) and the shell never parses the config itself (the separator has to be a real tab byte).</p> </li> <li> <p><strong>Single source of truth.</strong> The completion knows nothing about the config format, it asks the tool. Every TAB re-runs the command, so a profile added to the config appears immediately with its description; no shell restart, no re-registration. Profiles without a description yield the bare name.</p> </li> </ol> <p>Verify without pressing TAB:</p> <pre data-lang="fish" style="background-color:#2b303b;color:#c0c5ce;" class="language-fish "><code class="language-fish" data-lang="fish"><span style="background-color:#bf616a;color:#2b303b;">$</span><span> fish </span><span style="color:#bf616a;">-c </span><span>&#39;</span><span style="color:#a3be8c;">complete -C&quot;agentic &quot;</span><span>&#39; </span><span style="color:#bf616a;">fast </span><span>Pi with a fast model </span><span style="color:#bf616a;">private </span><span>Vibe with mistral and local models </span></code></pre>