Codex Completion: Shell Autocomplete Setup

codex completion generates shell autocomplete scripts — a small, easy-to-skip piece of setup that pays for itself the first time you're trying to remember an exact flag name or subcommand spelling and tab completion just gives it to you instead of requiring a trip to --help.

What this subcommand actually produces

Running codex completion for your specific shell outputs a script that, once wired into your shell's configuration, teaches that shell to suggest and complete Codex's own subcommands and flags as you type — the same category of feature most modern CLI tools offer, and one that's easy to forget to set up specifically because a CLI works perfectly well without it, just with more typing and more trips to documentation for exact flag names.

Why this is worth the five minutes it takes

Given how much of this site's own guidance involves exact flag names — --sandbox, --ask-for-approval, the specific values each one accepts — shell completion directly reduces the friction of actually using that guidance correctly. Instead of needing to recall or look up the precise spelling of workspace-write or danger-full-access, tab completion offers it, which also reduces the chance of a typo silently producing unexpected behavior because a misspelled value didn't error the way you'd expect.

Setting it up for your specific shell

The exact installation step differs by shell — bash, zsh, fish and others each have their own convention for where a completion script needs to live or how it needs to be sourced. codex completion --help on your installed version, or the current documentation, will have the specific instructions for your shell; this is worth checking directly rather than assuming a generic instruction applies uniformly, since shell completion setup conventions genuinely differ across shells in ways a one-size-fits-all guide can't reliably cover.

Keeping the completion script current after an update

Because completion scripts are generated from the CLI's own current set of subcommands and flags, an update to the CLI that adds a new subcommand or flag won't automatically appear in tab completion until the completion script itself is regenerated. It's worth re-running codex completion and reinstalling the script after any meaningful CLI update, the same way you'd re-check documentation after an update — a stale completion script isn't wrong, exactly, just incomplete relative to what the current CLI actually supports.

A small habit that compounds across a lot of usage

The value of shell completion isn't in any single use — it's genuinely marginal each time. It's in the cumulative effect across however many times you invoke Codex from a terminal, where a small amount of friction removed from typing a command correctly the first time adds up over weeks and months of regular use. For anyone using the CLI daily, this is a strong candidate for "small setup cost, ongoing benefit" — exactly the kind of investment that's easy to keep deferring precisely because no single instance of skipping it feels costly.

Where this fits in an onboarding process for a new team member

If your team maintains any kind of setup documentation or onboarding checklist for new developers picking up the Codex CLI, shell completion setup is a natural, low-friction item to include — it's a genuinely optional step nobody's blocked without, which makes it exactly the kind of small quality-of-life improvement that gets skipped by individuals working it out alone but is easy to bake into a shared onboarding process once someone thinks to add it.

Troubleshooting completion that isn't working

If tab completion doesn't seem to be functioning after setup, the most common causes are a completion script installed to the wrong location for your specific shell's convention, a shell configuration file that isn't actually sourcing the completion script, or a shell session that hasn't been restarted since the script was installed. Working through those three in order — right location, actually sourced, session restarted — resolves the large majority of setup issues without needing anything more exotic.

Why this is a small page about a small feature, deliberately

Not everything on this site is about cost or sandbox safety — some of it is simply about making the tool more pleasant and less error-prone to use day to day, and shell completion is squarely in that category. It's a minor page precisely because it's a minor feature, and it's included anyway because minor friction, repeated often enough, is worth removing.

Reducing typos in exactly the settings that matter most

It's worth connecting this back to the rest of this site's guidance specifically: a mistyped sandbox mode or approval value doesn't necessarily fail loudly — depending on how the CLI handles an unrecognized value, it might silently fall back to a default rather than erroring, which is exactly the kind of quiet misconfiguration this site warns about elsewhere. Tab completion, by offering the exact valid values rather than requiring you to type them from memory, is a small but genuine defense against that specific failure mode, on top of its more obvious convenience benefit.

Setting this up once, across every machine you use

If you work across more than one machine, it's worth including completion setup in whatever process you use to configure a new machine — the same install-and-update discipline this site recommends for the CLI itself applies here too, and a machine with the CLI installed but completion never configured is a small, persistent inconvenience worth fixing the same day you set the machine up, rather than living with it indefinitely and re-discovering the same minor annoyance every single day you work from that machine.