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/scrape.md
View on GitHub# Carapace Spec Scraping Guide
Generate carapace user specs by injecting a spec generator into CLI tools with available source code.
## How Scraping Works
The scraping approach:
1. **Checkout** the project with the corresponding base container
2. **Install** necessary dependencies
3. **Apply a patch** that injects the carapace spec generator into the command
4. **Set the entrypoint** to invoke the command so the spec is output on execution
5. **Capture** the generated YAML spec
This requires the CLI tool to use a [supported framework](#supported-frameworks) and have accessible source code.
## Supported Frameworks
| Framework | Scraper | Language | Notes |
|-----------|---------|----------|-------|
| **cobra** | carapace | Go | `carapace.Gen(cmd)` call injected via patch |
| **urfave/cli v2** | carapace-spec-urfavecli | Go | Register hidden `_carapace spec` subcommand |
| **kingpin v2** | carapace-spec-kingpin | Go | Register hidden `_carapace spec` subcommand |
| **kong** | carapace-spec-kong | Go | Register hidden `_carapace spec` subcommand |
| **clap (Rust)** | carapace-spec-clap | Rust | Implement `Generator` trait |
| **oclif** | oclif-carapace-spec-plugin | TypeScript | Install plugin, run `carapace-gen` |
## Example: Docker (Cobra-based)
The [scrape project](https://github.com/carapace-sh/scrape) demonstrates this pattern:
### Dockerfile
```dockerfile
FROM golang
ARG VERSION
WORKDIR /
RUN git clone https://github.com/docker/cli --branch "${VERSION}" --depth 1
ADD docker.patch /
WORKDIR /cli
RUN git apply ../docker.patch
RUN cp vendor.mod go.mod
RUN cp vendor.sum go.sum
RUN go get github.com/carapace-sh/carapace
RUN go mod tidy
RUN go mod vendor
RUN GOBIN=/usr/bin/ go install ./cmd/docker
ENTRYPOINT ["docker", "_carapace", "spec"]
```
### Patch (docker.patch)
```diff
diff --git a/cmd/docker/docker.go b/cmd/docker/docker.go
--- a/cmd/docker/docker.go
+++ b/cmd/docker/docker.go
@@ -10,6 +10,7 @@
"strings"
"syscall"
+ "github.com/carapace-sh/carapace"
"github.com/containerd/errdefs"
"github.com/docker/cli/cli"
pluginmanager "github.com/docker/cli/cli-plugins/manager"
@@ -147,6 +148,7 @@ func newDockerCommand(dockerCli *command.DockerCli) *cli.TopLevelCommand {
cmd.SetIn(dockerCli.In())
cmd.SetOut(dockerCli.Out())
cmd.SetErr(dockerCli.Err())
+ carapace.Gen(cmd)
opts, helpCmd = cli.SetupRootCommand(cmd)
```
**Key steps in the patch:**
- Add the `carapace-sh/carapace` import
- Call `carapace.Gen(cmd)` on the root command to register the `_carapace spec` subcommand
### Run the Container
```bash
docker build -t scrape-docker -f scrapers/docker/Dockerfile --build-arg VERSION=v29.5.2 scrapers/docker/
docker run --rm scrape-docker > docker.yaml
```
The resulting `docker.yaml` contains the full completion spec.
## Go-based Frameworks
### urfave/cli
```go
import (
"github.com/urfave/cli/v2"
"github.com/carapace-sh/carapace-spec-urfavecli/spec"
)
func main() {
app := &cli.App{}
spec.Register(app) // registers hidden "_carapace spec" subcommand
app.Run(os.Args)
}
```
Run: `myapp _carapace spec`
### kingpin
```go
import (
"github.com/alecthomas/kingpin/v2"
"github.com/carapace-sh/carapace-spec-kingpin/spec"
)
func main() {
app := kingpin.New("myapp", "My application")
spec.Register(app)
kingpin.Parse()
}
```
Run: `myapp _carapace spec`
### kong
```go
import (
"github.com/alecthomas/kong"
"github.com/carapace-sh/carapace-spec-kong/spec"
)
type Plugin struct {
Carapace struct {
Spec spec `cmd:"" name:"spec"`
} `cmd:"" name:"_carapace" hidden:""`
}
func main() {
ctx := kong.Parse(&CLI{}, &kong.Help{
Short: true,
}, kong.Bind(&Plugin{}))
ctx.Handle()
}
```
Run: `myapp _carapace spec`
## Rust (clap)
Implement the `Generator` trait:
```rust
use carapace_spec_clap::Spec;
use clap::{Arg, Command};
use clap_complete::generate;
use std::io;
fn main() {
let mut cmd = Command::new("example")
.about("example command")
.arg(Arg::new("flag").long("flag"));
generate(Spec, &mut cmd, "example", &mut io::stdout());
}
```
Build and run to output the spec.
## oclif (TypeScript)
```bash
<CLI> plugins install @cristiand391/oclif-carapace-spec-plugin
<CLI> carapace-gen
```
This generates a spec file and provides instructions to source it.
## Scraping Workflow
For new tools, follow this pattern:
1. **Identify the framework** (cobra, urfave/cli, kingpin, kong, clap, oclif)
2. **Create the Dockerfile:**
```dockerfile
FROM golang # or appropriate base image
ARG VERSION
WORKDIR /
RUN git clone <repo> --branch "${VERSION}" --depth 1
ADD <tool>.patch /
WORKDIR /<project>
RUN git apply ../<tool>.patch
RUN go get github.com/carapace-sh/carapace
RUN GOBIN=/usr/bin/ go install ./cmd/<tool>
ENTRYPOINT ["<tool>", "_carapace", "spec"]
```
3. **Create the patch** — inject `carapace.Gen(cmd)` (Go) or implement the generator trait (Rust)
4. **Build and run** the container, capturing stdout
## Output Location
Generated specs are typically saved to:
```
${UserConfigDir}/carapace/specs/<command>.yaml
```
| OS | Path |
|----|------|
| Linux | `~/.config/carapace/specs/` |
| macOS | `~/Library/Application Support/carapace/specs/` |
| Windows | `%APPDATA%\carapace\specs\` |
## Limitations
- **Source code required** — closed-source tools cannot be scraped this way
- **Supported frameworks only** — only frameworks with available scrapers are supported
- **Build dependencies** — the tool must be buildable (dependencies must resolve)
- **Plugin approach** — for some tools (like oclif), a plugin must be installed first
## Next Steps
To convert a scraped YAML spec to a native Go completer, see the **references/convert.md** skill.
## Reference Repositories
- [scrape](https://github.com/carapace-sh/scrape) — Docker-based scraping for Docker CLI, kubectl, gh, etc.
- [carapace-spec-clap](https://github.com/carapace-sh/carapace-spec-clap) — Rust clap scraper
- [carapace-spec-kingpin](https://github.com/carapace-sh/carapace-spec-kingpin) — Go kingpin scraper
- [carapace-spec-kong](https://github.com/carapace-sh/carapace-spec-kong) — Go kong scraper
- [carapace-spec-urfavecli](https://github.com/carapace-sh/carapace-spec-urfavecli) — Go urfave/cli scraper
- [oclif-carapace-spec-plugin](https://github.com/cristiand391/oclif-carapace-spec-plugin) — oclif pluginRelated 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 |