Where Does Carapace Store Custom Spec Files?
Carapace loads your own YAML completion specs from a specs folder inside the OS config dir, one file per command.
Last updated
Carapace ships over a thousand built-in completers, but your own additions live as YAML spec files in a specs folder under the OS config directory. Each file defines one command's flags and subcommands.
A personal spec with the same name as a built-in wins. That override trick rescues broken completions (a bridged kubectl is the classic example) without waiting for an upstream fix.
Where Carapace stores this, by platform
%APPDATA%\carapace\specs
Custom <name>.yaml specs, auto-loaded by carapace _carapace. The filename must equal the spec's name field. $XDG_CONFIG_HOME is honored on Windows too.
~/Library/Application Support/carapace/specs
Same specs layout. Register the loader line (source <(carapace _carapace)) in ~/.zshrc or ~/.bashrc; the specs folder alone does nothing without it.
~/.config/carapace/specs
Same specs layout under $XDG_CONFIG_HOME (default ~/.config). Shell-specific setup lines go in the usual rc files; see the carapace-bin setup docs per shell.
Frequently asked questions
I added a spec file but completion does not work. Why?
Drop the yaml into the specs folder and open a fresh shell. Registration happens at startup, so the current shell never sees the new file.
What must the spec file be named?
Name it exactly after the spec's name field (myspec.yaml for name: myspec). A mismatch means Carapace silently ignores the file.
Notice an outdated path? Let us know.