mirror of
https://github.com/upstash/context7.git
synced 2026-09-14 19:09:34 +08:00
Fahreddin Özcan
e127fa124a
* CTX7-2006: feat(cli): support on-premise setup with base URL * CTX7-2006: refactor(cli): isolate on-prem setup from outbound services * CTX7-2006: feat(cli): prompt securely for on-prem API key * CTX7-2006: test(cli): isolate on-prem API key scenarios * CTX7-2006: fix(cli): harden on-premise setup * CTX7-2006: refactor(cli): tighten on-premise setup boundaries * CTX7-2006: fix(cli): address on-premise review feedback * CTX7-2006: chore(cli): release setup support as patch
279 lines
11 KiB
Plaintext
279 lines
11 KiB
Plaintext
---
|
|
title: CLI
|
|
description: The ctx7 CLI — fetch library documentation and configure Context7 MCP from your terminal
|
|
---
|
|
|
|
The `ctx7` CLI is the command-line interface for Context7. It does two things:
|
|
|
|
- **Fetch library documentation** — resolve any library by name and query its up-to-date docs directly in your terminal, without opening a browser
|
|
- **Configure your AI coding agent** — set up the Context7 MCP server (or a CLI-based `docs` skill) for Claude Code, Cursor, OpenCode, and more with a single command
|
|
|
|
The CLI is useful both as a standalone tool (fetching docs while you code) and as a setup utility (wiring up Context7 for your AI coding agent).
|
|
|
|
## Installation
|
|
|
|
Requires Node.js 18 or later.
|
|
|
|
<Tabs>
|
|
<Tab title="npx (no install)">
|
|
Run ctx7 directly without installing anything. Useful for one-off commands or trying it out.
|
|
|
|
```bash
|
|
npx ctx7 --help
|
|
npx ctx7 library react
|
|
```
|
|
|
|
</Tab>
|
|
<Tab title="Global install">
|
|
Install globally for faster access — no `npx` prefix needed on every command.
|
|
|
|
```bash
|
|
npm install -g ctx7
|
|
|
|
# Verify installation
|
|
ctx7 --version
|
|
```
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
---
|
|
|
|
## Query Library Documentation
|
|
|
|
Fetching docs is a two-step process: first resolve the library name to get its Context7 ID, then use that ID to query documentation.
|
|
|
|
### Step 1 — ctx7 library
|
|
|
|
Searches the Context7 index by name and returns matching libraries. Pass a `query` describing what you're trying to do — this ranks results by relevance and helps when a library name is ambiguous or shared across multiple packages.
|
|
|
|
```bash
|
|
ctx7 library react "How to clean up useEffect with async operations"
|
|
ctx7 library nextjs "How to set up app router with middleware"
|
|
ctx7 library prisma "How to define one-to-many relations with cascade delete"
|
|
```
|
|
|
|
Each result includes:
|
|
|
|
| Field | Description |
|
|
| --------------------- | -------------------------------------------------------------------------- |
|
|
| **Library ID** | The identifier to pass to `ctx7 docs` (format: `/org/project`) |
|
|
| **Code Snippets** | Number of indexed code examples — higher means more documentation coverage |
|
|
| **Source Reputation** | Authority indicator: High, Medium, Low, or Unknown |
|
|
| **Benchmark Score** | Quality score from 0 to 100 |
|
|
| **Versions** | Version-specific IDs when available (format: `/org/project/version`) |
|
|
|
|
When multiple results come back, the best match is usually the one with the closest name, highest snippet count, and strongest reputation. If you need docs for a specific version, pick the matching version ID from the list.
|
|
|
|
```bash
|
|
# Fetch docs for a specific version
|
|
ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"
|
|
|
|
# Output as JSON for scripting
|
|
ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'
|
|
```
|
|
|
|
### Step 2 — ctx7 docs
|
|
|
|
Takes a library ID and a natural-language question, and returns relevant code snippets and explanations from the indexed documentation.
|
|
|
|
```bash
|
|
ctx7 docs /facebook/react "How to clean up useEffect with async operations"
|
|
ctx7 docs /vercel/next.js "How to add middleware that redirects unauthenticated users"
|
|
ctx7 docs /prisma/prisma "How to define one-to-many relations with cascade delete"
|
|
```
|
|
|
|
<Note>
|
|
Library IDs always start with `/`. Running `ctx7 docs react "hooks"` will fail — always use the
|
|
full ID returned by `ctx7 library` in Step 1.
|
|
</Note>
|
|
|
|
Queries work best when they're specific. Describe what you're trying to accomplish rather than using single keywords — `"How to set up authentication with JWT in Express.js"` returns much better results than `"auth"`.
|
|
|
|
The output contains two types of content: **code snippets** (titled, with language-tagged blocks) and **info snippets** (prose explanations with breadcrumb context). Both are formatted for readability in the terminal.
|
|
|
|
```bash
|
|
# 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 middleware for route protection" | grep -A 10 "middleware"
|
|
```
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
Configure Context7 for your AI coding agent. On first run, prompts you to choose between two modes:
|
|
|
|
- **MCP server** — registers the Context7 MCP server in your agent's config so it can call `resolve-library-id` and `query-docs` tools natively
|
|
- **CLI + Skills** — installs a `docs` skill that guides your agent to fetch up-to-date library docs using `ctx7` CLI commands (no MCP required)
|
|
|
|
### ctx7 setup
|
|
|
|
```bash
|
|
# Interactive — prompts for mode, then agent/install target
|
|
ctx7 setup
|
|
|
|
# Skip the mode prompt
|
|
ctx7 setup --mcp # MCP server mode
|
|
ctx7 setup --cli # CLI + Skills mode
|
|
|
|
# Target a specific agent (MCP mode)
|
|
ctx7 setup --claude
|
|
ctx7 setup --cursor
|
|
ctx7 setup --opencode
|
|
|
|
# Target a specific install location (CLI + Skills mode)
|
|
ctx7 setup --cli --claude # Claude Code (~/.claude/skills)
|
|
ctx7 setup --cli --cursor # Cursor (~/.cursor/skills)
|
|
ctx7 setup --cli --codex # Codex (~/.agents/skills)
|
|
ctx7 setup --cli --opencode # OpenCode (~/.agents/skills)
|
|
ctx7 setup --cli --antigravity # Antigravity (~/.agent/skills)
|
|
|
|
# Configure for current project only (default is global)
|
|
ctx7 setup --project
|
|
|
|
# Skip confirmation prompts
|
|
ctx7 setup --yes
|
|
```
|
|
|
|
**Authentication options:**
|
|
|
|
```bash
|
|
# Use an existing API key (works for both MCP and CLI + Skills mode)
|
|
ctx7 setup --api-key YOUR_API_KEY
|
|
|
|
# Use OAuth endpoint — MCP mode only (IDE handles the auth flow)
|
|
ctx7 setup --oauth
|
|
```
|
|
|
|
Without `--api-key` or `--oauth`, setup runs the OAuth device flow: it shows a verification link and short code that you open on any device to sign in, so it works the same locally or on a remote, headless, or SSH host. The device flow returns an API key that setup uses for authentication. `--oauth` is MCP-only — use it when an IDE handles the auth flow on your behalf.
|
|
|
|
### On-premise setup
|
|
|
|
Pass the root URL of your on-premise deployment with `--base-url`. Do not include `/mcp` or `/api`:
|
|
|
|
```bash
|
|
# MCP authentication disabled on the deployment
|
|
ctx7 setup --mcp --base-url https://context7.internal.example --codex
|
|
|
|
# MCP authentication enabled: the CLI requests the personal key with hidden input
|
|
ctx7 setup --mcp \
|
|
--base-url https://context7.internal.example \
|
|
--codex
|
|
|
|
# Non-interactive automation
|
|
CONTEXT7_API_KEY=ctx7op-... ctx7 setup --mcp --yes \
|
|
--base-url https://context7.internal.example \
|
|
--codex
|
|
```
|
|
|
|
The CLI checks `/api/auth/mcp` before writing configuration. It either configures anonymous access or writes `Authorization: Bearer <personal-key>`. When authentication is enabled and no key was provided, interactive setup requests the key with masked input. Use `--api-key` or `CONTEXT7_API_KEY` for non-interactive automation. On-premise setup uses Streamable HTTP and bundled rule/skill content, so the target does not need to serve Context7 Cloud skill endpoints.
|
|
|
|
When `--base-url` targets a custom deployment, setup skips the npm update check and telemetry and does not fetch rules or skills from GitHub or Context7 Cloud. After the CLI package is installed, the only network request made by setup is to the configured deployment. In a restricted environment, mirror `ctx7` and its dependencies in an internal npm registry and run the installed `ctx7` binary instead of `npx ctx7@latest`.
|
|
|
|
`--base-url` currently supports MCP setup only. It cannot be combined with `--oauth`, `--stdio`, or `--cli` for a custom deployment.
|
|
|
|
**What gets written — MCP mode:**
|
|
|
|
| File | Purpose |
|
|
| --------------------------------------------------- | ---------------------------------------------------------------- |
|
|
| `.mcp.json` / `.cursor/mcp.json` / `.opencode.json` | MCP server entry |
|
|
| Agent rules directory | Rule file — instructs the agent to use Context7 for library docs |
|
|
| Agent skills directory | `context7-mcp` skill |
|
|
|
|
**What gets written — CLI + Skills mode:**
|
|
|
|
| File | Purpose |
|
|
| ---------------------- | ------------------------------------------------------------------------------ |
|
|
| Agent skills directory | `docs` skill — guides the agent to use `ctx7 library` and `ctx7 docs` commands |
|
|
|
|
### ctx7 remove
|
|
|
|
Remove the setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent.
|
|
|
|
```bash
|
|
# Interactive
|
|
ctx7 remove
|
|
|
|
# Target specific agents
|
|
ctx7 remove --cursor
|
|
ctx7 remove --claude --project
|
|
|
|
# Remove both setup modes explicitly
|
|
ctx7 remove --cursor --all
|
|
|
|
# Remove only one setup mode
|
|
ctx7 remove --cursor --cli
|
|
ctx7 remove --claude --mcp
|
|
```
|
|
|
|
If you installed the CLI itself with `npm install -g ctx7`, remove that separately with `npm uninstall -g ctx7`. If you run Context7 with `npx ctx7`, there is no permanent CLI install to remove.
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
Most commands work without authentication. Log in to unlock higher rate limits on documentation commands.
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Log in (opens browser for OAuth)
|
|
ctx7 login
|
|
|
|
# Log in without opening the browser (prints URL instead)
|
|
ctx7 login --no-browser
|
|
|
|
# Check current login status
|
|
ctx7 whoami
|
|
|
|
# Log out
|
|
ctx7 logout
|
|
```
|
|
|
|
### API Key
|
|
|
|
Set an API key via environment variable to skip interactive login entirely — useful for CI or scripting:
|
|
|
|
```bash
|
|
export CONTEXT7_API_KEY=your_key
|
|
```
|
|
|
|
### When is authentication required?
|
|
|
|
| Feature | Required |
|
|
| -------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
|
| `ctx7 library` / `ctx7 docs` | No — login gives higher rate limits |
|
|
| Hosted `ctx7 setup` | Yes — unless `--api-key` is passed (`--oauth` also skips login for MCP mode) |
|
|
| On-premise `ctx7 setup --mcp --base-url ...` | Only when MCP authentication is enabled on the deployment |
|
|
|
|
---
|
|
|
|
## Telemetry
|
|
|
|
The CLI collects anonymous usage data to help improve the product. To disable:
|
|
|
|
```bash
|
|
# For a single command
|
|
CTX7_TELEMETRY_DISABLED=1 ctx7 docs /facebook/react "useEffect examples"
|
|
|
|
# Permanently — add to ~/.bashrc or ~/.zshrc
|
|
export CTX7_TELEMETRY_DISABLED=1
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Claude Code" icon="terminal" href="/clients/claude-code">
|
|
Set up Context7 in Claude Code
|
|
</Card>
|
|
<Card title="All Clients" icon="grid" href="/resources/all-clients">
|
|
Installation for every supported editor
|
|
</Card>
|
|
</CardGroup>
|