C7search

c7search

c7search wraps the Context7 v2 documentation API in a single static binary. It exposes two operations — resolve a library name to an ID, then fetch docs for that ID — with on-disk caching, secret redaction, retries, and semantic exit codes. Payload goes to stdout (markdown by default, JSON on demand); status messages go to stderr, so you can pipe stdout straight into the model context without filtering.

When to use

• "How do I X in <library>" / "show me <library>'s API for Y"
• Need current code examples or usage for a library or framework
• A library may have changed since the training cutoff
• Verifying the right API surface before generating code that uses it

Check the binary is installed

command -v c7search >/dev/null 2>&1 && c7search version || echo MISSING

If MISSING: the quickest install (and the only one needing no extra steps on macOS) is go install github.com/kevin-burns/c7search@latest, then ensure $(go env GOPATH)/bin is on $PATH. For release binaries and per-OS notes (macOS Gatekeeper, Windows SmartScreen), see the install section of the README: https://github.com/kevin-burns/c7search#install. If you can't install a binary, fall back to the curl-based context7 skill (same endpoints, no caching/retries): https://github.com/intellectronica/agent-skills/blob/main/skills/context7/SKILL.md

An API key is optional (CONTEXT7_API_KEY=ctx7sk-... lifts rate limits); the anonymous tier is fine for casual lookups. c7search auth status prints the key source and connectivity.

Workflow: resolve, then fetch

Prefer this two-step recipe. It uses the v2 endpoints exclusively and has predictable resolution.

Avoid c7search ask "..." except for a known-unambiguous lookup. ask does resolve+fetch in one shot over free-form v1 search, ranking the entire query string — so incidental feature keywords drag it to the wrong library. Real misses: a query mentioning "mock" resolved to a mock-testing lib, "plugins" to a plugins SDK, "register a tool in fastmcp" to a Go DI library. The more keywords you stuff in, the worse it gets. Instead resolve by library name (Step 1) — that anchors resolution to the actual library, then use --topic on docs to focus. Treat ask as a last resort.

Step 1 — resolve the library ID. Use --library-name when you know the name; the positional argument becomes the relevance topic:

c7search resolve --library-name <name> "<topic>" --json --limit 1 | jq -r '.[0].id'

Returns an ID like /vercel/next.js. For free-form lookups where you don't know the library name, omit --library-name and inspect the top results before fetching — that path ranks by trust score and can surface high-trust hits for unrelated libraries:

c7search resolve "<query>" --json --limit 5 | jq '.[] | {id, trustScore, totalSnippets, stars}'

Step 2 — fetch docs. Pass the resolved ID and a semantic --topic:

c7search docs "<library-id>" --topic "<topic>" --tokens <budget>

Examples

Two-step lookup (Next.js app-router middleware):

LIB=$(c7search resolve --library-name "next.js" "app router middleware" --json --limit 1 \
        | jq -r '.[0].id')
c7search docs "$LIB" --topic "middleware" --tokens 4000

Filter by language before ingesting (only TypeScript snippets):

LIB=$(c7search resolve --library-name "next.js" "server actions" --json --limit 1 \
        | jq -r '.[0].id')
c7search docs "$LIB" --topic "server actions" --tokens 6000 --json \
  | jq '.snippets[] | select(.codeLanguage | test("typescript|ts"))'

Output format

Default markdown is what Context7 token-optimizes for LLMs (Source: headers + fenced code blocks + --- separators). Feed it straight into context. Use --json only when you need to filter or sort snippets by a structured field (codeLanguage, codeTitle) before ingesting — it adds ~10–15% token overhead from the JSON envelope.

Token budget (--tokens)

Exit codes — branch on $?

if ! out=$(c7search docs "$LIB" --topic "$TOPIC" 2>&1); then
  case $? in
    1) echo "no docs found";;
    2) echo "API problem; retry later";;
    3) echo "check CONTEXT7_API_KEY";;
    *) echo "unknown error: $out";;
  esac
fi

Tips

• Cache works. Search results live 6 h on disk, docs payloads 24 h; repeated queries are ~10× faster. Use --no-cache only when you need fresh data (e.g. a release you just published).
• Library IDs accept /owner/repo or owner/repo. Leading slashes, whitespace, and case are normalized.
• --debug is safe. Bearer tokens and URL credentials are scrubbed before any log line reaches stderr.

Provenance

The c7search CLI is my own open-source tool (MIT): https://github.com/kevin-burns/c7search. It queries Context7's public documentation API, a third-party service — this skill and the CLI are not affiliated with or endorsed by Context7, and Context7's API terms and rate limits apply.