carapace-sh/carapace-bin / skills/carapace
carapace
VerifiedUse when working with carapace shell completion — integrating into CLIs, writing YAML specs, creating custom actions, building completion-aware lexers for DSLs, looking up macros, setting up shell completion, configuring choices/bridges, using the MCP server, or adding man page documentation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/action.md | markdown | 20.8 KB |
| references/choice.md | markdown | 9.0 KB |
| references/convert.md | markdown | 10.5 KB |
| references/env.md | markdown | 7.8 KB |
| references/integrate.md | markdown | 29.1 KB |
| references/lexer.md | markdown | 24.3 KB |
| references/macro.md | markdown | 19.4 KB |
| references/man.md | markdown | 13.5 KB |
| references/mcp.md | markdown | 14.0 KB |
| references/scrape.md | markdown | 6.3 KB |
| references/setup.md | markdown | 6.8 KB |
| references/spec.md | markdown | 8.0 KB |
| references/update.md | markdown | 11.2 KB |
references/setup.md
View on GitHub# Carapace Setup & Configuration
## Install
Download from [releases](https://github.com/carapace-sh/carapace-bin/releases) and add `carapace` to PATH.
| Method | Command |
|--------|---------|
| Homebrew | `brew install carapace` |
| AUR | `pamac install carapace-bin` |
| Mise | `mise use -g carapace@latest` |
| Nix | `nix-shell -p carapace` |
| Scoop | `scoop install extras/carapace-bin` |
| Winget | `winget install -e --id rsteube.Carapace` |
| Termux | `pkg install carapace` |
| DEB | `apt-get update && apt-get install carapace-bin` (from [fury.io](https://rsteube.fury.site/)) |
| RPM | `yum install carapace-bin` (from [fury.io](https://rsteube.fury.site/)) |
## Shell Integration
The config directory is `${UserConfigDir}/carapace/`:
| OS | Path |
|----|------|
| Linux | `~/.config/carapace/` |
| macOS | `~/Library/Application Support/carapace/` |
| Windows | `%APPDATA%\carapace\` |
> On **all** OSes, carapace respects `$XDG_CONFIG_HOME` for its config directory.
The `CARAPACE_BRIDGES` line is optional — see the **references/choice.md** skill for bridge details.
### Bash
```sh
# ~/.bashrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
source <(carapace _carapace)
```
### Bash (with ble.sh)
```sh
# ~/.bashrc (after loading ble.sh)
source <(carapace _carapace bash-ble)
```
### Zsh
```sh
# ${UserConfigDir}/zsh/.zshrc
autoload -U compinit && compinit
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
zstyle ':completion:*' format $'\e[2;37mCompleting %d\e[m'
source <(carapace _carapace)
```
Group order: `zstyle ':completion:*:git:*' group-order 'main commands' 'alias commands' 'external commands'`
### Fish
```sh
# ${UserConfigDir}/fish/config.fish
set -Ux CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense' # optional
carapace _carapace | source
```
### Elvish
```sh
# ${UserConfigDir}/elvish/rc.elv
set-env CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense' # optional
eval (carapace _carapace|slurp)
```
### Nushell
```sh
# ${UserConfigDir}/nushell/env.nu
$env.CARAPACE_BRIDGES = 'zsh,fish,bash,inshellisense' # optional
mkdir $"($nu.cache-dir)"
carapace _carapace nushell | save --force $"($nu.cache-dir)/carapace.nu"
# ${UserConfigDir}/nushell/config.nu
source $"($nu.cache-dir)/carapace.nu"
```
### Powershell
```powershell
# ${UserConfigDir}/powershell/Microsoft.PowerShell_profile.ps1
$env:CARAPACE_BRIDGES = 'zsh,fish,bash,inshellisense' # optional
Set-PSReadLineOption -Colors @{ "Selection" = "`e[7m" }
Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete
carapace _carapace | Out-String | Invoke-Expression
```
> `Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete` is **required**. Without it, raw ANSI escape codes appear. If using `Set-PSReadLineOption -EditMode Emacs`, place it **before** the key handler.
### Oil
```sh
# ${UserConfigDir}/oil/oshrc
export CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
source <(carapace _carapace)
```
### Xonsh
```sh
# ${UserConfigDir}/xonsh/rc.xsh
$CARAPACE_BRIDGES='zsh,fish,bash,inshellisense' # optional
$COMPLETIONS_CONFIRM=True
exec($(carapace _carapace))
```
### Tcsh
```sh
# ~/.tcshrc
setenv CARAPACE_BRIDGES 'zsh,fish,bash,inshellisense' # optional
set autolist
eval `carapace _carapace`
```
### Cmd (via clink)
```lua
-- ~/AppData/Local/clink/carapace.lua
load(io.popen('carapace _carapace cmd-clink'):read("*a"))()
```
Requires [clink](https://chrisant996.github.io/clink/).
## Environment Variables
Set all variables **before** sourcing the carapace init snippet.
### CARAPACE_BRIDGES
Comma-separated implicit bridge sources. Enables completion for commands carapace lacks a native completer for, by delegating to the shell's own completion. Unset by default — bridges are disabled unless this variable is set. See the **references/choice.md** skill for full bridge details.
### CARAPACE_EXCLUDES
Comma-separated completer names to exclude: `export CARAPACE_EXCLUDES='git,docker'`
### CARAPACE_COLOR
Whether to output color (default: enabled).
### CARAPACE_DESCRIPTION_LENGTH
Maximum description length in completions.
### CARAPACE_ENV
Register `get-env`/`set-env`/`unset-env` shell functions for env var completion. `0` = disabled, `1` = enabled (default).
### CARAPACE_HIDDEN
Show hidden commands/flags. `0` = disabled (default), `1` = enabled, `2` = enabled including `_carapace`.
### CARAPACE_LENIENT
Allow unknown flags. `0` = disabled (default), `1` = enabled. Overlays implicitly set this.
### CARAPACE_LOG
Enable logging. `0` = disabled (default), `1` = enabled.
### CARAPACE_MATCH
Case-insensitive matching. `0` = case sensitive (default), `1` = case insensitive.
### CARAPACE_MERGEFLAGS
Merge flags to single tag group. `0` = disabled, `1` = enabled (enabled by default in Zsh).
### CARAPACE_NOSPACE
Suffixes that prevent space after completion. `*` = match all (no space after any value).
### CARAPACE_TOOLTIP
Enable tooltip style. `0` = disabled (default), `1` = enabled. Only affects Powershell.
### CARAPACE_UNFILTERED
Skip final filtering step. Enables fuzzy completion in Fish, but only works for (mostly) static values. `0` = disabled (default), `1` = enabled.
### CARAPACE_BUILTINS
Experimental: enable shell builtin groups (`bash`, `bash-ble`, `cmd`, `elvish`, `fish`, `nushell`, `oil`, `powershell`, `tcsh`, `xonsh`, `zsh`) that complete commands and functions of the respective shell. Comma-separated group names.
### CARAPACE_ZSH_HASH_DIRS
Zsh hash directories used for command completion.
### CARAPACE_ZSH_STYLE_LIMIT
Maximum number of values to style in zsh (default: `300`).
## Overlays
YAML files in `${UserConfigDir}/carapace/overlays/` are merged on top of an existing completer at runtime, adding flags/subcommands without replacing it:
```yaml
# ${UserConfigDir}/carapace/overlays/doctl.yaml
name: doctl
persistentflags:
--output=: Desired output format [text|json]
completion:
flag:
output: [text, json]
```
Overlays implicitly set `CARAPACE_LENIENT`.
## Extensions
Extensions are standalone completer binaries that carapace-bin discovers automatically when on `PATH`. They use the carapace bridge protocol to provide richer completion than the built-in completer.
### carapace-aws
The only extension currently: [carapace-sh/carapace-aws](https://github.com/carapace-sh/carapace-aws).
Provides enriched AWS CLI completion by parsing [botocore](https://github.com/boto/botocore) service definitions (descriptions, colored highlighting, custom completions). Falls back to the official `aws_completer` for undefined completions.
**Setup**: Install `carapace-aws` and ensure it's on `PATH`. The built-in `aws` completer in carapace-bin automatically delegates to `carapace-aws` when detected:
```go
// completers/common/aws_completer/cmd/root.go
if _, err := exec.LookPath("carapace-aws"); err == nil {
return bridge.ActionCarapace("carapace-aws")
}
return bridge.ActionAws("aws")
```
No configuration needed — just install and it takes effect.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |