references/docs.md
# Documentation Commands
Retrieves and queries up-to-date documentation and code examples from Context7 for any programming library or framework. Two-step workflow: resolve the library name to get its ID, then query docs using that ID.
If the user already provided a library ID in `/org/project` or `/org/project/version` format, pass it directly to `ctx7 docs`.
To search all libraries with one command and no library ID, use [`ctx7 search`](#search-all-libraries).
## Step 1: Resolve a Library
Resolves a package/product name to a Context7-compatible library ID and returns matching libraries.
```bash
ctx7 library react "How to clean up useEffect with async operations"
ctx7 library nextjs "How to set up app router with a proxy"
ctx7 library prisma "How to define one-to-many relations with cascade delete"
```
Always pass a `query` argument — it is required and directly affects result ranking. Use the user's intent to form the query, which helps disambiguate when multiple libraries share a similar name. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
### Result fields
Each result includes:
- **Library ID** — Context7-compatible identifier (format: `/org/project`)
- **Name** — Library or package name
- **Description** — Short summary
- **Code Snippets** — Number of available code examples
- **Source Reputation** — Authority indicator (High, Medium, Low, or Unknown)
- **Benchmark Score** — Quality indicator (100 is the highest score)
- **Versions** — List of versions if available. Use one of those versions if the user provides a version in their query. The format is `/org/project/version`.
### Selection process
1. Analyze the query to understand what library/package the user is looking for
2. Select the most relevant match based on:
- Name similarity to the query (exact matches prioritized)
- Description relevance to the query's intent
- Documentation coverage (prioritize libraries with higher Code Snippet counts)
- Source reputation (consider libraries with High or Medium reputation more authoritative)
- Benchmark score (higher is better, 100 is the maximum)
3. If multiple good matches exist, acknowledge this but proceed with the most relevant one
4. If no good matches exist, clearly state this and suggest query refinements
5. For ambiguous queries, request clarification before proceeding with a best-guess match
IMPORTANT: Do not call `ctx7 library` more than 3 times per question. If you cannot find what you need after 3 calls, use the best result you have.
### Version-specific IDs
If the user mentions a specific version, use a version-specific library ID:
```bash
# General (latest indexed)
ctx7 docs /vercel/next.js "How to set up app router"
# Version-specific
ctx7 docs /vercel/next.js/v16.2.9 "How to set up app router"
```
The available versions are listed in the `ctx7 library` output. Use the closest match to what the user specified.
```bash
# Output as JSON for scripting
ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
```
## Step 2: Query Documentation
Retrieves up-to-date documentation and code examples for the resolved library.
You must call `ctx7 library` first to obtain the exact Context7-compatible library ID required to use this command, UNLESS the user explicitly provides a library ID in the format `/org/project` or `/org/project/version`.
```bash
ctx7 docs /facebook/react "How to clean up useEffect with async operations"
ctx7 docs /vercel/next.js "How to add an authentication proxy to app router"
ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
```
IMPORTANT: Do not call `ctx7 docs` more than 3 times per question. If you cannot find what you need after 3 calls, use the best information you have.
### Writing good queries
The query directly affects the quality of results. Be specific and include relevant details, but keep each query to one topic — if the question spans multiple distinct concepts, run a separate `ctx7 docs` command per concept instead of combining them, unless the question is about how the concepts interact. Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
| Quality | Example |
| --------------- | ---------------------------------------------------------- |
| Good | `"How to set up authentication with JWT in Express.js"` |
| Good | `"React useEffect cleanup function with async operations"` |
| Bad (too vague) | `"auth"` |
| Bad (too vague) | `"hooks"` |
| Bad (too broad) | `"routing and auth and caching in Next.js"` |
Describe what to look up in the library's documentation in the query when possible — vague one-word queries return generic results, and multi-topic queries dilute ranking and return shallow results for each topic.
The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context).
```bash
# Rank code examples in the language you write in first
ctx7 docs /websites/twilio "How to send an SMS" --language Ruby
# Output as structured JSON
ctx7 docs /facebook/react "How to use hooks for state management" --json
# Pipe to other tools — output is clean when not in a TTY (no spinners or colors)
ctx7 docs /facebook/react "How to use hooks for state management" | head -50
ctx7 docs /vercel/next.js "How to add a proxy for route protection" | grep -A5 "proxy"
```
## Search All Libraries
Searches the documentation of all libraries in one step. Context7 picks the libraries, so no library ID is needed.
```bash
ctx7 search "How to stream an OpenAI response from a Next.js route"
ctx7 search "How to validate a request body with a schema"
```
Do not include any sensitive or confidential information such as API keys, passwords, credentials, personal data, or proprietary code in your query.
If the library, version, or language is known, add them to narrow the results:
```bash
# Search specific libraries — a name or a library ID, repeat for up to four
ctx7 search "How to stream a response" --library Next.js --library /openai/openai-node
# Search a specific version
ctx7 search "How to cache a server function" --library Next.js --library-version 15.4.0
# Prefer results in the language you write in
ctx7 search "How to send an SMS" --library Twilio --language Ruby
# Output as structured JSON
ctx7 search "How to use hooks for state management" --library React --json
```
## Authentication
Works without authentication. For higher rate limits:
```bash
# Option A: environment variable
export CONTEXT7_API_KEY=your_key
# Option B: OAuth login
ctx7 login
```
references/setup.md
# Setup
## ctx7 setup
One-time command to configure Context7 for your AI coding agent. Prompts for mode on first run:
- **MCP server** — registers the Context7 MCP server so the agent can call tools natively
- **CLI + Skills** — installs a `find-docs` skill that guides the agent to use `ctx7` CLI commands (no MCP required)
```bash
ctx7 setup # Interactive — prompts for mode, then agent/install target
ctx7 setup --mcp # Skip prompt, use MCP server mode
ctx7 setup --cli # Skip prompt, use CLI + Skills mode
# MCP mode — target a specific agent
ctx7 setup --claude # Claude Code only
ctx7 setup --cursor # Cursor only
ctx7 setup --opencode # OpenCode only
ctx7 setup --pi # Pi only
# CLI + Skills mode — target a specific install location
ctx7 setup --cli --claude # Claude Code (~/.claude/skills)
ctx7 setup --cli --cursor # Cursor (~/.cursor/skills)
ctx7 setup --cli --antigravity # Antigravity (~/.agent/skills)
ctx7 setup --cli --pi # Pi (~/.agents/skills)
ctx7 setup --project # Configure current project instead of globally
ctx7 setup --yes # Skip confirmation prompts
```
**Authentication options:**
```bash
ctx7 setup --api-key YOUR_KEY # Use an existing API key (both MCP and CLI + Skills mode)
ctx7 setup --oauth # OAuth endpoint — MCP mode only (IDE handles the auth flow)
```
Without `--api-key` or `--oauth`, setup opens a browser for OAuth login. The device flow returns an API key that setup uses for authentication. `--oauth` is MCP-only.
**What gets written — MCP mode:**
- MCP server entry in the agent's config file (`.mcp.json` for Claude, `.cursor/mcp.json` for Cursor, `.opencode.json` for OpenCode)
- A Context7 rule file instructing the agent to use Context7 for library docs
- A `context7-mcp` skill in the agent's skills directory
**What gets written — CLI + Skills mode:**
- A `find-docs` skill in the chosen agent's skills directory, guiding the agent to use `ctx7 library` and `ctx7 docs` commands
- A Context7 rule file instructing the agent to use the `ctx7` commands for library docs
SKILL.md
---
name: context7-cli
description: Use the ctx7 CLI to fetch library documentation and configure Context7 MCP. Activate when the user mentions "ctx7" or "context7", needs current docs for any library, or needs to set up Context7 for their AI coding agent.
---
# ctx7 CLI
The Context7 CLI does two things: fetches up-to-date library documentation and sets up Context7 MCP for your editor.
Make sure the CLI is up to date before running commands:
```bash
npm install -g ctx7@latest
```
Or run directly without installing:
```bash
npx ctx7@latest <command>
```
## What this skill covers
- **[Documentation](references/docs.md)** — Fetch current docs for any library. Use when writing code, verifying API signatures, or when training data may be outdated.
- **[Setup](references/setup.md)** — Configure Context7 MCP for Claude Code / Cursor / OpenCode.
## Quick Reference
```bash
# Documentation
ctx7 search <query> # Search all libraries in one step
ctx7 library <name> <query> # Step 1: resolve library ID
ctx7 docs <libraryId> <query> # Step 2: fetch docs
# Setup
ctx7 setup # Configure Context7 MCP (interactive)
ctx7 login # Log in for higher rate limits
ctx7 whoami # Check current login status
```
## Authentication
```bash
ctx7 login # Opens browser for OAuth
ctx7 login --no-browser # Prints URL instead of opening browser
ctx7 logout # Clear stored tokens
ctx7 whoami # Show current login status (name + email)
```
Most commands work without login. Exception: `ctx7 setup` requires it unless `--api-key` or `--oauth` is passed. Login also unlocks higher rate limits on docs commands.
Set an API key via environment variable to skip interactive login entirely:
```bash
export CONTEXT7_API_KEY=your_key
```
## Common Mistakes
- Library IDs require a `/` prefix — `/facebook/react` not `facebook/react`
- Always run `ctx7 library` first — `ctx7 docs react "hooks"` will fail without a valid ID