context7-cli 0.4.3

---
name: context7-skill
description: Use the context7-cli binary to search library documentation and API references from the terminal via the Context7 REST API. Invoke when the user asks about library APIs, wants up-to-date documentation, or mentions Context7. Covers library search, documentation fetch, key management, and output formatting.
version: 0.4.3
---

## English

### When to invoke this skill

- User asks about a library's API, method signatures, or configuration options
- User wants up-to-date documentation for any library or framework
- User mentions: Context7, context7-cli, library search, API docs, documentation fetch
- Before writing code that depends on an external library's API
- When training data may be outdated for a specific library version

### Prerequisites

```bash
# 1. Verify context7 is installed
which context7           # Unix/Linux/macOS
where context7           # Windows CMD
Get-Command context7     # Windows PowerShell

# 2. Verify API keys are configured
context7 keys list

# 3. If no keys are listed, add one (ask the user for their key or direct them to https://context7.com)
context7 keys add ctx7sk-THEIR-KEY-HERE
```

If `context7` is not installed:

```bash
cargo install context7-cli    # requires Rust toolchain from https://rustup.rs
```

### Usage patterns

#### Pattern 1 — Search for a library by name

```bash
context7 library <name> [optional-context] --json
```

- Always pass `--json` for machine-readable output
- `optional-context` improves result ranking (e.g., `"effect hooks"`, `"async channels"`)

Examples:

```bash
context7 library react --json
context7 library axum "middleware routing" --json
context7 library tokio "mpsc channel" --json
context7 library vue --json
```

#### Pattern 2 — Fetch documentation for a specific library

```bash
context7 docs <library-id> --query "<question>" --text
# Short form: -q is an alias for --query
context7 docs <library-id> -q "<question>" --text
```

- Use `library-id` from Pattern 1 output (format: `/org/repo`)
- Use `--text` for LLM context insertion (plain text, no ANSI)
- Use `--json` for structured parsing
- Use `-q` as a short alias for `--query`

Examples:

```bash
context7 docs /reactjs/react.dev --query "useEffect and cleanup" --text
context7 docs /tokio-rs/tokio -q "spawn_blocking use cases" --text
context7 docs /rust-lang/rust -q "lifetime annotations" --text
context7 docs /tokio-rs/axum --query "tower middleware" --json
```

#### Pattern 3 — 2-step discovery workflow (recommended)

Always use `library` before `docs` to get the exact library ID:

```bash
# Step 1: Find the library ID
context7 library react --json
# Outputs: [{"id": "/reactjs/react.dev", "title": "React", "trustScore": 9.8}, ...]

# Step 2: Fetch the docs using that ID
context7 docs /reactjs/react.dev --query "useState and useEffect" --text
```

### Output parsing

**Library search output (`--json`):**

```json
[
  {
    "id": "/reactjs/react.dev",
    "title": "React",
    "description": "A JavaScript library for building user interfaces",
    "trustScore": 9.8
  }
]
```

- `id`: exact string to pass to `context7 docs`
- `trustScore`: 0–10; results with score < 7 may be less relevant
- Use `jaq '.[0].id'` to extract the top result's ID

**Documentation output (`--json`):**

```json
{
  "id": "/reactjs/react.dev",
  "snippets": [
    {
      "pageTitle": "useEffect",
      "codeTitle": "Basic useEffect example",
      "codeDescription": "The useEffect hook lets you synchronize a component with an external system.",
      "codeLanguage": "javascript",
      "codeTokens": 42,
      "codeId": "https://react.dev/reference/react/useEffect",
      "codeList": [
        { "language": "javascript", "code": "useEffect(() => { /* cleanup */ }, [deps]);" }
      ],
      "relevance": 0.95,
      "model": "gemini-2.5-flash"
    }
  ]
}
```

- `snippets[].codeTitle`: title of the code snippet
- `snippets[].codeId`: source URL for citation

### Examples with expected outputs

**Example 1 — Find React library**

```bash
context7 library react --json
```

Expected:

```json
[
  {"id": "/reactjs/react.dev", "title": "React", "trustScore": 9.8},
  {"id": "/preactjs/preact", "title": "Preact", "trustScore": 8.1}
]
```

**Example 2 — Fetch useEffect docs**

```bash
context7 docs /reactjs/react.dev --query "useEffect cleanup function" --text
```

Expected: plain Markdown text about `useEffect`, its cleanup function, and dependency array — ready to insert into an LLM context window.

**Example 3 — Key management check**

```bash
context7 keys list
```

Expected:

```
1. ctx7sk-abcd...xyz9 (added on 2026-04-08)
```

(Values are always masked — never full keys in output.)

### Error handling

| Exit code | Meaning | Action |
|-----------|---------|--------|
| 0 | Success | Parse output |
| 1 | Error (no keys, network, 400 Bad Request) | Show error message to user |
| Non-zero | Any failure | Read stderr for details |

Common error messages and their solutions:

- `No API key found` → run `context7 keys add ctx7sk-...`
- `401 Unauthorized` → key invalid; run `context7 keys remove <N>` and add a new one
- `429 Too Many Requests` → already retried with backoff; wait ~10s and retry
- `All API keys failed` → all keys exhausted; get new key from context7.com

### Key management commands

```bash
context7 keys add <key>        # add a key (persisted to XDG config)
context7 keys list             # list all keys (masked)
context7 keys remove <index>   # remove key by 1-based index
context7 keys clear --yes      # remove all keys (no prompt)
context7 keys path             # show config file path
context7 keys export           # export to .env format (full values)
context7 keys import <file>    # import from .env file
# Rotation is automatic — each request shuffles keys randomly.
```

### Language control (v0.2.0+)

```bash
# Force English output (useful in multilingual environments)
context7 --lang en library react --json

# Force Portuguese output
context7 --lang pt docs /reactjs/react.dev --query "hooks" --text

# Permanent override via env var
export CONTEXT7_LANG=en
```

Auto-detect order: `--lang` flag → `CONTEXT7_LANG` env var → system locale → English default.

### Environment variables

| Variable | Purpose |
|----------|---------|
| `CONTEXT7_API_KEYS` | Comma-separated API keys (overrides config file) |
| `CONTEXT7_LANG` | UI language: `en` or `pt` |
| `CONTEXT7_HOME` | Alternative XDG config directory (mainly for tests and CI) |
| `RUST_LOG` | Log level: `error`, `warn`, `info`, `debug`, `trace` |

### Rules for this skill

1. **Always use `library` before `docs`** — never guess a library ID
2. **Always pass `--json`** for machine-readable output
3. **Never expose full API keys** — use `context7 keys list` (masked) or avoid showing key operations in output
4. **Respect trust scores** — flag results with `trustScore < 7` as lower confidence
5. **Use `--text` for LLM context** — cleaner than `--json` when inserting docs into a prompt
6. **Handle errors gracefully** — the CLI retries automatically; if it still fails, show the error message to the user
7. **Use `--lang en`** for consistent output language in multilingual pipelines

---

## Português

### Quando invocar esta skill

- O usuário pergunta sobre a API de uma biblioteca, assinaturas de métodos ou opções de configuração
- O usuário quer documentação atualizada de qualquer biblioteca ou framework
- O usuário menciona: Context7, context7-cli, busca de biblioteca, API docs, busca de documentação
- Antes de escrever código que depende da API de uma biblioteca externa
- Quando os dados de treinamento podem estar desatualizados para uma versão específica de uma biblioteca

### Pré-requisitos

```bash
# 1. Verificar se o context7 está instalado
which context7           # Unix/Linux/macOS
where context7           # Windows CMD
Get-Command context7     # Windows PowerShell

# 2. Verificar se as chaves de API estão configuradas
context7 keys list

# 3. Se nenhuma chave estiver listada, adicionar uma (peça a chave ao usuário ou direcione para https://context7.com)
context7 keys add ctx7sk-CHAVE-DO-USUARIO
```

Se o `context7` não estiver instalado:

```bash
cargo install context7-cli    # requer Rust toolchain de https://rustup.rs
```

### Padrões de uso

#### Padrão 1 — Buscar uma biblioteca por nome

```bash
context7 library <nome> [contexto-opcional] --json
```

- Sempre passe `--json` para saída legível por máquina
- `contexto-opcional` melhora o ranking dos resultados (ex: `"hooks de efeito"`, `"canais async"`)

Exemplos:

```bash
context7 library react --json
context7 library axum "middleware rotas" --json
context7 library tokio "canal mpsc" --json
context7 library vue --json
```

#### Padrão 2 — Buscar documentação de uma biblioteca específica

```bash
context7 docs <id-da-biblioteca> --query "<pergunta>" --text
# Forma curta: -q é um alias para --query
context7 docs <id-da-biblioteca> -q "<pergunta>" --text
```

- Use o `id-da-biblioteca` do output do Padrão 1 (formato: `/org/repo`)
- Use `--text` para inserir no contexto de um LLM (texto plano, sem ANSI)
- Use `--json` para parsing estruturado
- Use `-q` como alias curto para `--query`

Exemplos:

```bash
context7 docs /reactjs/react.dev --query "useEffect e cleanup" --text
context7 docs /tokio-rs/tokio -q "casos de uso do spawn_blocking" --text
context7 docs /rust-lang/rust -q "anotações de lifetime" --text
context7 docs /tokio-rs/axum --query "tower middleware" --json
```

#### Padrão 3 — Fluxo de descoberta em 2 passos (recomendado)

Sempre use `library` antes de `docs` para obter o ID exato da biblioteca:

```bash
# Passo 1: Encontrar o ID da biblioteca
context7 library react --json
# Saída: [{"id": "/reactjs/react.dev", "title": "React", "trustScore": 9.8}, ...]

# Passo 2: Buscar a documentação com esse ID
context7 docs /reactjs/react.dev --query "useState e useEffect" --text
```

### Parsing do output

**Output de busca de biblioteca (`--json`):**

```json
[
  {
    "id": "/reactjs/react.dev",
    "title": "React",
    "description": "A JavaScript library for building user interfaces",
    "trustScore": 9.8
  }
]
```

- `id`: string exata para passar para `context7 docs`
- `trustScore`: 0–10; resultados com score < 7 podem ser menos relevantes
- Use `jaq '.[0].id'` para extrair o ID do primeiro resultado

**Output de documentação (`--json`):**

```json
{
  "id": "/reactjs/react.dev",
  "snippets": [
    {
      "pageTitle": "useEffect",
      "codeTitle": "Exemplo básico de useEffect",
      "codeDescription": "O hook useEffect permite sincronizar um componente com um sistema externo.",
      "codeLanguage": "javascript",
      "codeTokens": 42,
      "codeId": "https://react.dev/reference/react/useEffect",
      "codeList": [
        { "language": "javascript", "code": "useEffect(() => { /* cleanup */ }, [deps]);" }
      ],
      "relevance": 0.95,
      "model": "gemini-2.5-flash"
    }
  ]
}
```

- `snippets[].codeTitle`: título do snippet de código
- `snippets[].codeId`: URL da fonte para citação

### Exemplos com outputs esperados

**Exemplo 1 — Encontrar a biblioteca React**

```bash
context7 library react --json
```

Esperado:

```json
[
  {"id": "/reactjs/react.dev", "title": "React", "trustScore": 9.8},
  {"id": "/preactjs/preact", "title": "Preact", "trustScore": 8.1}
]
```

**Exemplo 2 — Buscar documentação do useEffect**

```bash
context7 docs /reactjs/react.dev --query "função de cleanup do useEffect" --text
```

Esperado: texto Markdown plano sobre `useEffect`, sua função de cleanup e array de dependências — pronto para inserir na janela de contexto de um LLM.

**Exemplo 3 — Verificação de gerenciamento de chaves**

```bash
context7 keys list
```

Esperado:

```
1. ctx7sk-abcd...xyz9 (adicionada em 2026-04-08)
```

(Os valores são sempre mascarados — nunca chaves completas na saída.)

### Tratamento de erros

| Código de saída | Significado | Ação |
|-----------------|-------------|------|
| 0 | Sucesso | Fazer parsing do output |
| 1 | Erro (sem chaves, rede, 400 Bad Request) | Mostrar mensagem de erro ao usuário |
| Não-zero | Qualquer falha | Ler stderr para detalhes |

Mensagens de erro comuns e soluções:

- `Nenhuma chave de API encontrada` → execute `context7 keys add ctx7sk-...`
- `401 Unauthorized` → chave inválida; execute `context7 keys remove <N>` e adicione uma nova
- `429 Too Many Requests` → já fez retry com backoff; aguarde ~10s e tente novamente
- `Todas as chaves de API falharam` → todas as chaves esgotadas; obtenha nova chave em context7.com

### Comandos de gerenciamento de chaves

```bash
context7 keys add <chave>       # adicionar chave (persistida no config XDG)
context7 keys list              # listar todas as chaves (mascaradas)
context7 keys remove <índice>   # remover chave por índice 1-based
context7 keys clear --yes       # remover todas as chaves (sem prompt)
context7 keys path              # exibir caminho do arquivo config
context7 keys export            # exportar em formato .env (valores completos)
context7 keys import <arquivo>  # importar de arquivo .env
# A rotação é automática — cada requisição embaralha as chaves aleatoriamente.
```

### Controle de idioma (v0.2.0+)

```bash
# Forçar saída em inglês (útil em ambientes multilíngues)
context7 --lang en library react --json

# Forçar saída em português
context7 --lang pt docs /reactjs/react.dev --query "hooks" --text

# Override permanente via variável de ambiente
export CONTEXT7_LANG=pt
```

Ordem de detecção: flag `--lang` → variável `CONTEXT7_LANG` → locale do sistema → inglês (padrão).

### Variáveis de ambiente

| Variável | Finalidade |
|----------|-----------|
| `CONTEXT7_API_KEYS` | Chaves de API separadas por vírgula (sobrepõe o arquivo de config) |
| `CONTEXT7_LANG` | Idioma da interface: `en` ou `pt` |
| `CONTEXT7_HOME` | Diretório XDG alternativo (principalmente para testes e CI) |
| `RUST_LOG` | Nível de log: `error`, `warn`, `info`, `debug`, `trace` |

### Regras desta skill

1. **Sempre use `library` antes de `docs`** — nunca adivinhe um ID de biblioteca
2. **Sempre passe `--json`** para saída legível por máquina
3. **Nunca exponha chaves de API completas** — use `context7 keys list` (mascarado) ou evite mostrar operações de chaves no output
4. **Respeite os trust scores** — sinalize resultados com `trustScore < 7` como de menor confiança
5. **Use `--text` para contexto de LLM** — mais limpo que `--json` ao inserir docs em um prompt
6. **Trate erros com elegância** — a CLI faz retry automaticamente; se ainda falhar, mostre a mensagem de erro ao usuário
7. **Use `--lang en`** para linguagem de output consistente em pipelines multilíngues