context7-cli 0.5.0

Search library documentation from your terminal — zero runtime, bilingual (EN/PT), multi-key rotation
Documentation

context7-cli

Crates.io docs.rs CI License

English

Search any library's docs from your terminal — one binary, zero runtime, instant results.

What is context7-cli?

context7-cli queries the Context7 REST API directly from your shell. No Node, no Python, no daemon. One static binary that installs in seconds and works identically on Linux, macOS, and Windows.

Key properties:

  • Single binary — zero runtime dependencies, ships as a static executable
  • XDG-compliant storage — API keys stored in ~/.config/context7/config.toml with chmod 600
  • Multi-key rotation — automatic shuffle with exponential backoff retry (500ms → 1s → 2s, up to 5 attempts)
  • Bilingual UI — English and Brazilian Portuguese output, auto-detected from system locale
  • Privacy-first — no telemetry, no analytics; keys are masked in all logs and list output
  • Secure key handling — API keys wrapped in a secure newtype with automatic memory zeroing on drop (zeroize)
  • Structured output — colored terminal, --json for pipes, --text for LLM context windows
  • Graceful signal handling — Ctrl+C triggers proper cleanup and exits with code 130

Why context7-cli?

  • Zero context switching — stay in your terminal, no browser tabs needed
  • Pipe-friendly — --text output feeds directly into LLMs, scripts, and pipelines
  • Works over SSH — full functionality on headless servers and remote machines
  • CI/CD native — set CONTEXT7_API_KEYS and use it in any automation workflow

Quick Start (30 seconds)

# 1 — Install
cargo install context7-cli

# 2 — Add your API key (get one at https://context7.com)
context7 keys add ctx7sk-YOUR-KEY-HERE

# 3 — Search a library
context7 library react

Expected output:

Libraries found:
────────────────────────────────────────────────────────────
1. React (trust 10.0/10)
   /reactjs/react.dev
   React.dev is the official documentation website for React...

# 4 — Fetch documentation
context7 docs /tokio-rs/tokio --query "spawn_blocking" --text

No Rust toolchain? Download a prebuilt binary from the GitHub Releases page. Available targets:

  • x86_64-unknown-linux-gnu (Linux x86_64 glibc)
  • x86_64-unknown-linux-musl (Linux x86_64 musl — Alpine containers)
  • aarch64-unknown-linux-gnu (ARM64 Linux glibc — Raspberry Pi 4+, AWS Graviton)
  • aarch64-unknown-linux-musl (ARM64 Linux musl — Alpine containers on ARM)
  • x86_64-pc-windows-msvc (Windows x86_64 zip)
  • macOS Universal Binary (arm64 + x86_64)

Commands

Search Libraries

context7 library react
context7 lib axum "middleware"           # alias: lib, search
context7 search tokio "mpsc channel"    # optional semantic context

Aliases: library, lib, search are equivalent.

Fetch Documentation

context7 docs /reactjs/react.dev
context7 docs /tokio-rs/tokio --query "spawn_blocking"
context7 docs /tokio-rs/tokio -q "spawn_blocking" --text   # --text strips all markup
context7 doc  /rust-lang/rust --query "lifetimes" --json   # alias: doc, context

Use --text to pipe clean prose directly into an LLM context window. Use --json to process with jaq or scripts.

Key Management

Command Description
context7 keys add ctx7sk-... Add an API key
context7 keys list List saved keys (masked)
context7 keys list --json List keys as JSON array
context7 keys remove 2 Remove key by 1-based index
context7 keys clear --yes Remove all keys
context7 keys path Show config file path
context7 keys export Export to .env format
context7 keys import .env Import from .env file

Key rotation is automatic — every request shuffles keys randomly.

Output Formats

Flag Description Best for
(none) Colored, human-readable Terminal reading
--json NDJSON (one JSON object per line) Scripts, pipes, jaq
--text Plain text, no markup (docs only) LLM context windows
--lang en|pt Force UI language Multilingual workflows

When --json is active, output uses NDJSON format (one JSON object per line). Each line includes a type field (event category) and a timestamp field (ISO 8601). Example: context7 library react --json | jq -c '.type'

Global Flags

Flag Description
--no-color Disable colored output (also via NO_COLOR env var)
--plain Plain text without ANSI (incompatible with --json)
-v, --verbose Increase verbosity (-v info, -vv debug, -vvv trace)
--quiet Suppress all output except errors

Environment Variables

Variable Description Example
CONTEXT7_API_KEYS Comma-separated keys (overrides config file) ctx7sk-key1,ctx7sk-key2
CONTEXT7_HOME Override XDG config directory $HOME/.dotfiles/context7
CONTEXT7_LANG Force UI language en or pt
RUST_LOG Log verbosity warn, info, debug, trace
NO_COLOR Any value disables colors (convention: no-color.org) 1
CLICOLOR_FORCE Set to 1 to force colors in pipes 1

Language auto-detect order: --lang flag → CONTEXT7_LANG → system locale → English.

Integration Patterns

# Pipe documentation into an LLM prompt
context7 docs /tokio-rs/tokio -q "channels" --text | llm "explain buffered channels"

# Extract library IDs for scripting
context7 library axum --json | jaq '.[0].id'

# Search documentation with ripgrep
context7 docs /rust-lang/rust --text | rg "lifetime"

# Loop over multiple libraries
for lib in tokio axum serde; do
  context7 library "$lib" --json | jaq '.[0].id'
done

# CI/CD — no config file needed
CONTEXT7_API_KEYS="ctx7sk-key-01" context7 docs /tokio-rs/tokio -q "spawn" --text

Quick Reference

Operation Command
Search library context7 library NAME [CONTEXT]
Fetch docs context7 docs ID [-q TEXT] [--text|--json]
Add key context7 keys add ctx7sk-...
List keys context7 keys list [--json]
Remove key context7 keys remove N
Clear all keys context7 keys clear --yes
Config path context7 keys path
Export keys context7 keys export
Import keys context7 keys import FILE
Force language context7 --lang en|pt COMMAND
Shell completions context7 completions bash|zsh|fish|powershell|elvish

Shell Completions

# Bash
context7 completions bash > ~/.local/share/bash-completion/completions/context7

# Zsh (add ~/.zfunc to fpath in .zshrc first)
context7 completions zsh > ~/.zfunc/_context7

# Fish
context7 completions fish > ~/.config/fish/completions/context7.fish

# PowerShell (add to $PROFILE)
context7 completions powershell >> $PROFILE

# Elvish
context7 completions elvish > ~/.config/elvish/lib/context7.elv

Exit Codes

Code Meaning Example
0 Success Successful search, key added, completions generated
1 Generic runtime error No API keys configured, empty key, invalid index
2 Invalid CLI usage Unknown subcommand, conflicting flags (--text + --json)
65 Invalid input data (EX_DATAERR) Malformed API key, unparseable response
66 Resource not found (EX_NOINPUT) Library or doc ID not found (API 404)
69 Service unavailable after retry (EX_UNAVAILABLE) API down after all retry attempts exhausted
74 I/O or network error (EX_IOERR) Connection refused, DNS failure, disk write error
77 Permission/auth denied (EX_NOPERM) Invalid API key (401), rate limited (429)
130 Interrupted by Ctrl+C (SIGINT) User pressed Ctrl+C during operation

Troubleshooting

command not found: context7 Add ~/.cargo/bin to your PATH: export PATH="$HOME/.cargo/bin:$PATH"

"No API key configured" Run context7 keys add ctx7sk-YOUR-KEY or set CONTEXT7_API_KEYS env var.

"Library not found" (404) The library ID must come from context7 library NAME. Copy the /org/repo path from the search results, not from GitHub.

Rate limited (429) The CLI retries automatically with exponential backoff (up to 5 attempts). Add a second key with context7 keys add to increase throughput.

macOS Gatekeeper blocks the binary Run: xattr -d com.apple.quarantine context7 && chmod +x context7 Or install via cargo install context7-cli to bypass Gatekeeper entirely.

No colors in terminal Use --no-color or --plain for plain output, or set NO_COLOR=1. Verify your terminal supports ANSI escape sequences.

--text and --json together give an error These flags are mutually exclusive. Use one or the other: context7 docs /org/repo --text or context7 docs /org/repo --json.

keys remove 0 gives "Invalid index" Indices are 1-based. Run context7 keys list first to see the current indices, then use context7 keys remove <N> with N ≥ 1.

context7 library without arguments gives an error The library name is required. Provide a search term: context7 library react

What's New in v0.5.0

  • NDJSON structured output — --json now emits one JSON object per line with type and timestamp fields for easy pipeline processing
  • Global flags — --no-color, --plain, -v/--verbose, --quiet for full control over output behavior
  • Expanded exit codes — sysexits-compatible codes (65, 66, 69, 74, 77, 130) for precise error classification in scripts
  • Secure key zeroize — API keys wrapped in a secure newtype with automatic memory zeroing on drop
  • ARM64 Linux builds — aarch64-unknown-linux-gnu and aarch64-unknown-linux-musl targets for Raspberry Pi 4+, AWS Graviton, and ARM Alpine containers
  • Color control — NO_COLOR and CLICOLOR_FORCE environment variables supported (no-color.org convention)
  • Graceful Ctrl+C — signal handler performs proper cleanup and exits with code 130

See CHANGELOG.md for the complete history.

Full Documentation

Português

Pesquise a documentação de qualquer biblioteca no terminal — um binário, sem runtime, resultados instantâneos.

O que é o context7-cli?

O context7-cli consulta a API REST do Context7 diretamente do seu shell. Sem Node, sem Python, sem daemon. Um único binário estático que instala em segundos e funciona de forma idêntica no Linux, macOS e Windows.

Propriedades principais:

  • Binário único — zero dependências de runtime, distribuído como executável estático
  • Armazenamento XDG — chaves de API salvas em ~/.config/context7/config.toml com chmod 600
  • Rotação multi-chave — shuffle automático com retry e backoff exponencial (500ms → 1s → 2s, até 5 tentativas)
  • Interface bilíngue — saída em inglês e português brasileiro, detectado automaticamente pelo locale do sistema
  • Privacidade em primeiro lugar — sem telemetria, sem analytics; chaves mascaradas em todos os logs e no output de listagem
  • Chaves seguras com zeroize — chaves de API encapsuladas em newtype seguro com limpeza automática de memória ao sair de escopo
  • Saída estruturada — colorido para terminal, --json para pipes, --text para janelas de contexto de LLM
  • Tratamento gracioso de sinais — Ctrl+C executa limpeza adequada e encerra com código 130

Por que o context7-cli?

  • Zero troca de contexto — fique no terminal, sem abas de browser
  • Amigável para pipes — saída --text alimenta LLMs, scripts e pipelines diretamente
  • Funciona via SSH — funcionalidade completa em servidores headless e máquinas remotas
  • Nativo para CI/CD — configure CONTEXT7_API_KEYS e use em qualquer workflow de automação

Início Rápido (30 segundos)

# 1 — Instalar
cargo install context7-cli

# 2 — Adicionar sua chave de API (obtenha em https://context7.com)
context7 keys add ctx7sk-SUA-CHAVE-AQUI

# 3 — Buscar uma biblioteca
context7 library react

Saída esperada:

Bibliotecas encontradas:
────────────────────────────────────────────────────────────
1. React (confiança 10.0/10)
   /reactjs/react.dev
   React.dev é o site oficial de documentação do React...

# 4 — Buscar documentação
context7 docs /tokio-rs/tokio --query "spawn_blocking" --text

Sem toolchain Rust? Baixe um binário pré-compilado na página de Releases do GitHub. Targets disponíveis:

  • x86_64-unknown-linux-gnu (Linux x86_64 glibc)
  • x86_64-unknown-linux-musl (Linux x86_64 musl — containers Alpine)
  • aarch64-unknown-linux-gnu (ARM64 Linux glibc — Raspberry Pi 4+, AWS Graviton)
  • aarch64-unknown-linux-musl (ARM64 Linux musl — containers Alpine em ARM)
  • x86_64-pc-windows-msvc (Windows x86_64 zip)
  • Universal Binary macOS (arm64 + x86_64)

Comandos

Buscar Bibliotecas

context7 library react
context7 lib axum "middleware"          # alias: lib, search
context7 search tokio "canal mpsc"     # contexto semântico opcional

Aliases: library, lib, search são equivalentes.

Buscar Documentação

context7 docs /reactjs/react.dev
context7 docs /tokio-rs/tokio --query "spawn_blocking"
context7 docs /tokio-rs/tokio -q "spawn_blocking" --text   # --text remove toda marcação
context7 doc  /rust-lang/rust --query "lifetimes" --json   # alias: doc, context

Use --text para enviar prosa limpa diretamente para a janela de contexto de um LLM. Use --json para processar com jaq ou scripts.

Gerenciamento de Chaves

Comando Descrição
context7 keys add ctx7sk-... Adicionar uma chave de API
context7 keys list Listar chaves salvas (mascaradas)
context7 keys list --json Listar chaves como array JSON
context7 keys remove 2 Remover chave por índice 1-based
context7 keys clear --yes Remover todas as chaves
context7 keys path Exibir caminho do arquivo de configuração
context7 keys export Exportar no formato .env
context7 keys import .env Importar de arquivo .env

A rotação de chaves é automática — cada requisição embaralha as chaves aleatoriamente.

Formatos de Saída

Flag Descrição Melhor para
(nenhuma) Colorido, legível por humanos Leitura no terminal
--json NDJSON (um objeto JSON por linha) Scripts, pipes, jaq
--text Texto plano, sem marcação (apenas docs) Janelas de contexto de LLM
--lang en|pt Forçar idioma da interface Fluxos multilíngues

Quando --json está ativo, a saída usa formato NDJSON (um objeto JSON por linha). Cada linha inclui um campo type (categoria do evento) e um campo timestamp (ISO 8601). Exemplo: context7 library react --json | jq -c '.type'

Flags Globais

Flag Descrição
--no-color Desabilitar saída colorida (também via variável NO_COLOR)
--plain Texto plano sem ANSI (incompatível com --json)
-v, --verbose Aumentar verbosidade (-v info, -vv debug, -vvv trace)
--quiet Suprimir toda saída exceto erros

Variáveis de Ambiente

Variável Descrição Exemplo
CONTEXT7_API_KEYS Chaves separadas por vírgula (substitui o arquivo de configuração) ctx7sk-chave1,ctx7sk-chave2
CONTEXT7_HOME Override do diretório de configuração XDG $HOME/.dotfiles/context7
CONTEXT7_LANG Forçar idioma da interface en ou pt
RUST_LOG Verbosidade de log warn, info, debug, trace
NO_COLOR Qualquer valor desabilita cores (convenção: no-color.org) 1
CLICOLOR_FORCE Definir como 1 para forçar cores em pipes 1

Ordem de detecção de idioma: flag --lang → CONTEXT7_LANG → locale do sistema → inglês.

Padrões de Integração

# Enviar documentação para um LLM
context7 docs /tokio-rs/tokio -q "channels" --text | llm "explique canais com buffer"

# Extrair IDs de biblioteca para scripts
context7 library axum --json | jaq '.[0].id'

# Buscar na documentação com ripgrep
context7 docs /rust-lang/rust --text | rg "lifetime"

# Iterar sobre múltiplas bibliotecas
for lib in tokio axum serde; do
  context7 library "$lib" --json | jaq '.[0].id'
done

# CI/CD — sem arquivo de configuração necessário
CONTEXT7_API_KEYS="ctx7sk-chave-01" context7 docs /tokio-rs/tokio -q "spawn" --text

Referência Rápida

Operação Comando
Buscar biblioteca context7 library NOME [CONTEXTO]
Buscar docs context7 docs ID [-q TEXTO] [--text|--json]
Adicionar chave context7 keys add ctx7sk-...
Listar chaves context7 keys list [--json]
Remover chave context7 keys remove N
Limpar todas as chaves context7 keys clear --yes
Caminho da configuração context7 keys path
Exportar chaves context7 keys export
Importar chaves context7 keys import ARQUIVO
Forçar idioma context7 --lang en|pt COMANDO
Autocompletar context7 completions bash|zsh|fish|powershell|elvish

Autocompletar no Shell

# Bash
context7 completions bash > ~/.local/share/bash-completion/completions/context7

# Zsh (adicione ~/.zfunc ao fpath no .zshrc primeiro)
context7 completions zsh > ~/.zfunc/_context7

# Fish
context7 completions fish > ~/.config/fish/completions/context7.fish

# PowerShell (adicione ao $PROFILE)
context7 completions powershell >> $PROFILE

# Elvish
context7 completions elvish > ~/.config/elvish/lib/context7.elv

Códigos de Saída

Código Significado Exemplo
0 Sucesso Busca realizada, chave adicionada, completions geradas
1 Erro genérico de runtime Sem chaves configuradas, chave vazia, índice inválido
2 Uso inválido da CLI Subcomando desconhecido, flags conflitantes (--text + --json)
65 Dados de entrada inválidos (EX_DATAERR) Chave de API malformada, resposta impossível de parsear
66 Recurso não encontrado (EX_NOINPUT) Biblioteca ou ID de doc não encontrado (API 404)
69 Serviço indisponível após retry (EX_UNAVAILABLE) API fora do ar após todas as tentativas esgotadas
74 Erro de I/O ou rede (EX_IOERR) Conexão recusada, falha DNS, erro de escrita em disco
77 Permissão/autenticação negada (EX_NOPERM) Chave de API inválida (401), rate limited (429)
130 Interrompido por Ctrl+C (SIGINT) Usuário pressionou Ctrl+C durante operação

Resolução de Problemas

command not found: context7 Adicione ~/.cargo/bin ao seu PATH: export PATH="$HOME/.cargo/bin:$PATH"

"Nenhuma chave de API configurada" Execute context7 keys add ctx7sk-SUA-CHAVE ou defina a variável CONTEXT7_API_KEYS.

"Biblioteca não encontrada" (404) O ID da biblioteca deve vir de context7 library NOME. Copie o caminho /org/repo dos resultados da busca, não do GitHub.

Rate limit (429) A CLI faz retry automaticamente com backoff exponencial (até 5 tentativas). Adicione uma segunda chave com context7 keys add para aumentar o throughput.

macOS Gatekeeper bloqueia o binário Execute: xattr -d com.apple.quarantine context7 && chmod +x context7 Ou instale via cargo install context7-cli para contornar o Gatekeeper completamente.

Sem cores no terminal Use --no-color ou --plain para saída sem marcação, ou defina NO_COLOR=1. Verifique se o terminal suporta escape sequences ANSI.

--text e --json juntos causam erro Essas flags são mutuamente exclusivas. Use uma ou outra: context7 docs /org/repo --text ou context7 docs /org/repo --json.

keys remove 0 retorna "Índice inválido" Os índices são 1-based. Execute context7 keys list primeiro para ver os índices atuais, depois use context7 keys remove <N> com N ≥ 1.

context7 library sem argumentos retorna erro O nome da biblioteca é obrigatório. Forneça um termo de busca: context7 library react

Novidades na v0.5.0

  • Saída NDJSON estruturada — --json agora emite um objeto JSON por linha com campos type e timestamp para processamento em pipelines
  • Flags globais — --no-color, --plain, -v/--verbose, --quiet para controle completo do comportamento de saída
  • Códigos de saída expandidos — códigos compatíveis com sysexits (65, 66, 69, 74, 77, 130) para classificação precisa de erros em scripts
  • Zeroize seguro de chaves — chaves de API encapsuladas em newtype seguro com limpeza automática de memória ao sair de escopo
  • Builds ARM64 Linux — targets aarch64-unknown-linux-gnu e aarch64-unknown-linux-musl para Raspberry Pi 4+, AWS Graviton e containers Alpine em ARM
  • Controle de cores — variáveis de ambiente NO_COLOR e CLICOLOR_FORCE suportadas (convenção no-color.org)
  • Ctrl+C gracioso — handler de sinal executa limpeza adequada e encerra com código 130

Veja CHANGELOG.md para o histórico completo.

Documentação Completa

License

Dual-licensed under MIT OR Apache-2.0, at your choice.

Copyright 2026 Danilo Aguiar <daniloaguiarbr@pm.me>