Adding Autocomplete to Your CLI Agent

A developer at a logistics startup shipped an internal CLI agent his team loved in the demo and abandoned within a week. The reason wasn't the model or the tools. It was that nobody could remember what to type. The agent supported thirty commands and exposed exactly zero of them until you got the syntax perfect. People typed agent hepl, got an error, and went back to Slack. Adding cli agent autocomplete would have saved the whole project — and it's the feature most agent builders skip because it feels cosmetic. It isn't.

Discoverability is what turns a powerful tool into a used tool. Good cli agent autocomplete means users find capabilities by pressing Tab instead of reading docs, and that difference decides whether your agent survives contact with real humans.

What Is CLI Agent Autocomplete?

Autocomplete is the system that suggests completions as a user types — subcommands, flags, file paths, or in an agent's case, natural-language intents. There are two distinct layers, and good tools ship both.

Shell completion runs in bash, zsh, or fish and completes your top-level commands and flags at the system prompt, before your program even starts. In-REPL completion runs inside your interactive agent session, where you control the whole experience and can offer smarter, context-aware suggestions.

[object Object],
,[object Object], prompt_toolkit ,[object Object], PromptSession
,[object Object], prompt_toolkit.completion ,[object Object], WordCompleter

INTENTS = [,[object Object],, ,[object Object],, ,[object Object],, ,[object Object],, ,[object Object],]
completer = WordCompleter(INTENTS, ignore_case=,[object Object],)
session = PromptSession(completer=completer)

,[object Object], ,[object Object],:
    text = session.prompt(,[object Object],)
    handle(text)

What this does: Creates an interactive prompt that suggests your intent verbs as the user types. Press Tab or start typing and the menu appears — no memorization required.

Why CLI Agent Autocomplete Matters More for Agents

Traditional CLIs have stable, documented commands. Agents are different: their capabilities are defined by a tool registry that changes as you add tools, and users interact in fuzzy natural language. That combination makes discoverability harder, which makes autocomplete more valuable, not less.

Consider three people hitting the same agent:

A junior developer who just joined and has no idea the agent can even roll back a deploy. Autocomplete surfaces rollback the moment they type r, teaching them the tool exists.

A release manager running the same five commands daily who wants zero friction — Tab-completing dep to deploy shaves seconds off every invocation, dozens of times a day.

An on-call SRE at 3 a.m. whose memory is unreliable under stress and who needs the tool to remind them what's possible without opening a wiki.

Every one of them is better served by completion than by documentation, because documentation requires leaving the terminal and autocomplete doesn't.

⚡ Pro tip: Generate your completion list from the same registry that defines your tools, not a hand-maintained array. When you add a tool, completion updates for free — and the two can never drift out of sync, which is the bug that makes users stop trusting Tab.

How Do You Add Shell Completion?

Shell completion lives outside your program, in a script the user's shell sources. The cleanest approach is to have your CLI generate that script so it always matches your current commands.

[object Object], sys

,[object Object], ,[object Object],(,[object Object],):
    joined = ,[object Object],.join(intents)
    ,[object Object],(,[object Object],)

,[object Object], ,[object Object],(sys.argv) > ,[object Object], ,[object Object], sys.argv[,[object Object],] == ,[object Object],:
    emit_bash_completion(,[object Object],, [,[object Object],, ,[object Object],, ,[object Object],, ,[object Object],])

What this does: Prints a bash completion function wired to your current intent list. Users run agent --completion >> ~/.bashrc once, and Tab starts completing your commands at the system prompt.

The generated-script approach beats a static committed file because the script can never go stale — it's produced from live data every time. Frameworks like Click and Typer in Python, or oclif in Node, can emit completion scripts for you, and it's worth using them if you're already on those tools.

⚡ Pro tip: Complete values, not just command names. If the user types logs and Tab, offer the actual service names pulled from your environment. Context-aware value completion is what separates a tool that feels smart from one that just echoes a fixed list.

How Do You Autocomplete Natural Language?

This is the part generic guides miss. For an agent that takes English, don't just complete verbs — complete phrase templates. Offer skeletons the user fills in.

[object Object], prompt_toolkit.completion ,[object Object], Completer, Completion

TEMPLATES = [
    ,[object Object],,
    ,[object Object],,
    ,[object Object],,
]

,[object Object], ,[object Object],(,[object Object],):
    ,[object Object], ,[object Object],(,[object Object],):
        word = document.text_before_cursor.lower()
        ,[object Object], t ,[object Object], TEMPLATES:
            ,[object Object], t.split()[,[object Object],].startswith(word.split()[,[object Object],] ,[object Object], word ,[object Object], ,[object Object],):
                ,[object Object], Completion(t, start_position=-,[object Object],(word))

What this does: Suggests full natural-language templates as the user types, so they learn the shapes of requests the agent handles well. It nudges fuzzy input toward phrasings the model parses reliably.

⚠️ Common mistake: Completing only exact command syntax while your agent advertises "just ask in plain English." Users get whiplash — the marketing says natural language, the Tab key says rigid commands. Either commit to template completion for phrases or set expectations honestly. Mismatched affordances erode trust faster than missing features.

How Do You Make Autocomplete Fast Enough?

Completion has one hard rule: it must be faster than the user can type, or they'll turn it off. That means everything happening on a keystroke has to be local and instant — no network, no disk churn, no model call. Build an in-memory index once at startup and query it in microseconds.

[object Object], ,[object Object],:
    ,[object Object], ,[object Object],(,[object Object],):
        ,[object Object],
        ,[object Object],.index = ,[object Object],(,[object Object],(
            ,[object Object],(registry.intents) + registry.known_services()
        ))
    ,[object Object], ,[object Object],(,[object Object],):
        p = prefix.lower()
        ,[object Object], [x ,[object Object], x ,[object Object], ,[object Object],.index ,[object Object], x.startswith(p)][:,[object Object],]

What this does: Precomputes a flat, sorted index of everything completable and answers each keystroke from memory, capped at eight results. No I/O happens in the hot path, so completion stays instant even as your registry grows.

The trap here is fetching completion data on every keystroke — hitting an API to list services each time Tab is pressed. That turns a snappy feature into a laggy one, and lag is fatal for autocomplete. Refresh the index on a timer or on explicit command, never on keypress.

⚡ Pro tip: Cap suggestions at seven or eight items. A completion menu with forty entries is just a wall the user has to read, which is slower than typing. Rank by recency or frequency and show the short, useful head of the list.

Should CLI Agent Autocomplete Use the Model?

Tempting, but mostly no — and understanding why is the non-obvious part. A model call takes hundreds of milliseconds; typing takes tens. Putting the model in the per-keystroke path makes completion feel broken. The model's place is a separate, explicit affordance, not the Tab key.

[object Object],
completer = FastCompleter(registry)

,[object Object],
,[object Object], ,[object Object],(,[object Object],):
    ,[object Object],
    resp = client.messages.create(
        model=,[object Object],, max_tokens=,[object Object],,
        system=,[object Object],,
        messages=[{,[object Object],: ,[object Object],, ,[object Object],: partial_request}],
    )
    ,[object Object], resp.content[,[object Object],].text

What this does: Keeps instant local completion on Tab, and reserves the model for a deliberate "help me phrase this" command. The user opts into the slow-but-smart path when they want it, and keeps the fast path for everything else.

This hybrid is what good agents converge on. Static completion handles the ninety percent case at zero latency; a model-backed suggest command handles the "I don't even know how to ask" case where the wait is worth it. Trying to make one mechanism do both jobs makes both worse.

⚡ Pro tip: For the model-backed suggester, constrain it to return one of your real intents rather than free text. A suggestion the user can't act on is noise — but "did you mean: rollback payments?" is a command they can run with one copy-paste.

How Do You Support Fuzzy Matching?

Prefix matching — completing only what the user has typed from the start of a word — is where most tools stop, and it quietly fails real users. Someone who half-remembers a command types dpl for deploy or rlbk for rollback, gets nothing back, and concludes the feature is broken. Subsequence matching fixes this: match if the typed characters appear in order anywhere in the candidate, not just at the front.

[object Object], ,[object Object],(,[object Object],):
    it = ,[object Object],(candidate.lower())
    ,[object Object], ,[object Object],(c ,[object Object], it ,[object Object], c ,[object Object], typed.lower())

,[object Object], ,[object Object],(,[object Object],):
    exact = [x ,[object Object], x ,[object Object], index ,[object Object], x.startswith(prefix.lower())]
    fuzzy = [x ,[object Object], x ,[object Object], index ,[object Object], subseq_match(prefix, x) ,[object Object], x ,[object Object], ,[object Object], exact]
    ,[object Object], (exact + fuzzy)[:,[object Object],]

What this does: Returns prefix matches first, then subsequence matches, so dpl still surfaces deploy while exact prefixes stay ranked on top. The iter trick walks each candidate once, checking the typed characters appear in order.

The ordering matters as much as the matching. Show exact prefixes first because they're what the user most likely means, then fuzzy hits below as a safety net. Flip that order and a stray subsequence match can bury the obvious completion, which feels worse than no fuzzy matching at all. Get the ranking right and the tool feels like it reads minds; get it wrong and it feels random.

Common Mistakes to Avoid

The failure at the top of this article was one mistake: shipping power without discoverability. But there are subtler ones.

Hardcoding the completion list separately from the tool registry guarantees drift; generate both from one source. Offering completion that's slower than typing — because you're hitting an API on every keystroke — makes users disable it; keep completion local and instant, and save model calls for actual requests. And forgetting shell completion entirely means power users who never enter your REPL get nothing; support both layers.

There's a safety angle people miss too. If your agent has any destructive intents, be deliberate about whether they appear in completion at all. Auto-completing rollback teaches users it exists, which is good — but auto-completing a raw delete verb and letting someone Tab straight into it, half-read, is how accidents happen. For dangerous actions, requiring the full word to be typed is a small, useful speed bump. Completion is a teaching tool, and what you choose to surface teaches users what's normal to run.

Finally, measure it. Log which completions users accept versus type past, and you'll learn which suggestions actually help. If nobody ever accepts a given completion, it's noise — cut it. Good cli agent autocomplete earns its place with data, not assumptions.

Conclusion

Autocomplete isn't polish you add at the end. For an agent whose capabilities live in a growing registry and whose interface is fuzzy language, it's the difference between a tool people use and a tool people forget. Generate completions from your real tool registry, support both shell and in-REPL layers, and complete phrase templates, not just verbs.

The templates you offer for completion are, in effect, a curated set of prompts — the request shapes your agent handles best. Keeping those in a library like PromptABCD lets you refine them over time and reuse them across tools, so the phrasings that work well become a shared asset instead of a list buried in one project's source.