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/env.md
View on GitHub# Carapace Environment Variable Completion Guide
Define and customize environment variable name and value completions in [carapace](https://carapace.sh).
## Overview
Environment variable completion has two layers:
| Layer | Location | Mechanism |
|-------|----------|-----------|
| Built-in | `pkg/actions/env/*.go` | Go `init()` registration into `knownVariables` map |
| User YAML | `~/.config/carapace/variables/*.yaml` | Loaded at runtime, overrides built-in |
The public API is in `pkg/actions/env`:
| Function | Purpose |
|----------|---------|
| `ActionNames()` | Completes environment variable names (built-in + custom) |
| `ActionValues(varName)` | Completes values for a specific variable |
| `ActionNameValues(positional)` | Combined `NAME=VALUE` completion (flag or positional) |
## Go-Based Definitions
### Registration Pattern
Each file in `pkg/actions/env/` registers a group via `init()`:
```go
package env
func init() {
knownVariables["docker"] = func() variables {
return variables{
Condition: conditions.ConditionPath("docker"),
Variables: map[string]string{
"DOCKER_HOST": "Daemon socket to connect to",
"DOCKER_BUILDKIT": "Enable BuildKit for docker build",
},
VariableCompletion: map[string]carapace.Action{
"DOCKER_HOST": carapace.ActionValues("tcp://", "unix://"),
},
}
}
}
```
Key points:
- **Group key** is a logical name (e.g. `"git"`, `"docker"`, `"aws"`, `"common"`)
- **Factory function** — `knownVariables["key"] = func() variables { ... }` for lazy evaluation
- **`Condition`** — gates the entire group; `nil` means always active
- **`VariableCompletion`** keys must be a subset of `Variables` keys (enforced by test)
### Conditions
| Condition | Description |
|-----------|-------------|
| `nil` | Always active (e.g. `common`, `carapace`) |
| `conditions.ConditionPath("docker")` | Active when `docker` is on `$PATH` |
| `conditions.ConditionPath("aws")` | Active when `aws` is on `$PATH` |
| Build tags in filename | Platform gating (e.g. `common_unix.go`) — no runtime condition needed |
Available conditions from `pkg/conditions`:
- **`Path`** — executable exists in PATH
- **`Parent`** — parent directory contains given file/directory
- **`Os`** — current `runtime.GOOS` matches
- **`Arch`** — current `runtime.GOARCH` matches
### Completion Action Patterns
| Pattern | Example |
|---------|---------|
| Boolean (true/false) | `carapace.ActionValues("true", "false").StyleF(style.ForKeyword)` |
| Boolean (0/1) | `carapace.ActionValuesDescribed("0", "disabled", "1", "enabled").StyleF(style.ForKeyword)` |
| Styled boolean | `carapace.ActionStyledValuesDescribed("0", "disabled", style.Carapace.KeywordNegative, "1", "enabled", style.Carapace.KeywordPositive)` |
| Directories | `carapace.ActionDirectories()` |
| Files | `carapace.ActionFiles()` |
| Path list | `carapace.ActionDirectories().List(string(os.PathListSeparator))` |
| Comma list | `carapace.ActionValues(...).UniqueList(",")` |
| Tool-specific action | `aws.ActionProfiles()`, `git.ActionConfigValues(...)` |
| Bridge to other completer | `bridge.ActionCarapaceBin("go").Split()` |
| MultiParts (structured value) | `carapace.ActionMultiParts(";", ...)` |
| Batch (union) | `carapace.Batch(carapace.ActionFiles(), carapace.ActionValues("off").StyleF(...)).ToA()` |
| Static values | `carapace.ActionValues("off", "on", "auto")` |
### Helper Variables
Reuse common actions within a group:
```go
_bool := carapace.ActionValues("true", "false").StyleF(style.ForKeyword)
// ...
"NO_COLOR": _bool,
"TERM_DUMB": _bool,
```
### Adding a New Tool Group
1. Create `pkg/actions/env/<tool>.go`
2. Register with `init()` using `knownVariables["<tool>"]`
3. Add `Condition` if the tool isn't always available
4. List all relevant env vars in `Variables` with descriptions
5. Add completion actions for vars where values are known/enumerable
6. Ensure every `VariableCompletion` key exists in `Variables`
## User YAML Definitions
Custom environment variable definitions live in `~/.config/carapace/variables/<group>.yaml`. They can define new variables, add completions, or override built-in definitions.
### YAML Format
```yaml
condition:
- $Parent([.git])
variables:
CUSTOM_VAR: description of the variable
OTHER_VAR: another variable
completion:
variable:
CUSTOM_VAR:
- "value1\tdescription1"
- "value2\tdescription2"
OTHER_VAR:
- $carapace.tools.git.RemoteBranches
```
> **Note:** Values containing a tab character (`\t`) for description or style must be wrapped in double quotes, otherwise YAML treats `\t` as a literal backslash followed by `t` (two characters), and the style/description will not be applied.
### Fields
| Field | Type | Description |
|-------|------|-------------|
| `condition` | `[]string` | Condition macro strings — group is only active when all conditions pass |
| `variables` | `map[string]string` | Variable name → description |
| `completion.variable` | `map[string][]string` | Variable name → list of completion spec strings |
### Completion Spec Strings
Each entry in a variable's completion list is a spec string:
| Format | Meaning |
|--------|---------|
| `value` | Static value |
| `"value\tdescription"` | Value with description (tab-separated, must be double-quoted) |
| `"value\tdescription\tstyle"` | Value with description and style (tab-separated, must be double-quoted) |
| `$macroname` | Macro reference (e.g. `$files`, `$directories`) |
| `$carapace.tools.<tool>.<Action>` | Fully qualified macro |
| `\|\|\|` suffix | Action modifiers after `\|\|\|` (e.g. `$files \|\|\| $uniquelist(,)`) |
> **Important:** Values containing a tab character (`\t`) for description or style **must be wrapped in double quotes** (`"value\tdescription\tstyle"`). YAML does not interpret `\t` as a tab in unquoted strings — it remains as literal backslash-`t`, and the description/style will not be applied.
### Overriding Built-in Definitions
User YAML files **override** built-in completions. When a custom YAML defines a completion for a variable that also has a built-in completion, the custom one replaces it.
```yaml
# ~/.config/carapace/variables/proxy.yaml
variables:
HTTPS_PROXY: override existing variable description
completion:
variable:
HTTPS_PROXY:
- "https://localhost:8443\tdevelopment\tgreen"
- "https://proxy.company:443\tproduction\tred"
```
> **Note:** Values containing a tab character (`\t`) for description or style must be wrapped in double quotes, otherwise YAML treats `\t` as a literal backslash followed by `t` (two characters), and the style/description will not be applied.
### Condition Examples
```yaml
# Only active inside a git repository
condition:
- $Parent([.git])
# Only active on Linux
condition:
- $Os([linux])
# Only active when docker is in PATH
condition:
- $Path([docker])
```
## How Completion Flows Work
### Name Completion (`ActionNames`)
Merges two sources:
1. `actionKnownEnvironmentVariables()` — all groups from `knownVariables` where `Condition` passes
2. `actionCustomEnvironmentVariables()` — all YAML files from `~/.config/carapace/variables/`
OS-level environment variables (from `os.ActionEnvironmentVariables()`, styled in blue) are **not** part of `ActionNames` — they are only added by the combined `ActionNameValues` completion for its name position.
### Value Completion (`ActionValues`)
For a given variable name:
1. Look up built-in completion in `knownVariables`
2. Check user YAML files for overrides
3. If a custom YAML defines a completion for that variable, it replaces the built-in
4. If no completion is found at all, falls back to `carapace.ActionFiles()`
### Combined Name=Value (`ActionNameValues`)
Two modes:
- **Positional** (`positional=true`): First positional completes names, second completes values
- **Flag** (`positional=false`): `ActionMultiPartsN("=", 2, ...)` — first part is name (with `NoSpace`), second part is value
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 |