# context7
CLI Rust nativa para a API REST do [Context7](https://context7.com) — busca de bibliotecas e documentação técnica diretamente no terminal.
[](https://crates.io/crates/context7-cli)
[](https://github.com/daniloaguiarbr/context7-cli#licença)
[](#instalação)
---
## O que é
`context7` é um binário Rust nativo que substitui o servidor MCP Context7 (Node.js). Ele consulta a API REST pública `https://context7.com/api/v1` para buscar bibliotecas e documentação técnica diretamente no terminal — sem Node.js, sem Python, sem runtime adicional.
**Destaques:**
- Binário único sem dependências de runtime
- Suporte a múltiplas chaves de API com rotação automática e retry com backoff exponencial
- Saída colorida para humanos ou JSON para integrações e pipes
- Armazenamento seguro de chaves via XDG (`~/.config/context7/config.toml`) com `chmod 600`
- Logs persistentes: terminal (stderr com ANSI) + arquivo XDG com rotação por deleção
- Zero `unwrap()` em produção, zero `println!` de debug
---
## Instalação
### Via `cargo install`
```bash
cargo install context7-cli
```
> **Nota:** O crate publicado no crates.io chama-se `context7-cli`. Após a instalação,
> o binário executável é `context7` (sem o sufixo `-cli`). Use `context7 --help` para começar.
### A partir do código-fonte
```bash
git clone https://github.com/daniloaguiarbr/context7-cli
cd context7-cli
cargo build --release
# Binário em: target/release/context7
```
### Instalação global manual
```bash
cp target/release/context7 ~/.local/bin/context7
# ou
sudo cp target/release/context7 /usr/local/bin/context7
```
---
## Configuração de chaves de API
O binário descobre chaves de API por uma **hierarquia de 4 camadas**, em ordem de precedência:
| 1 (maior) | Variável de ambiente `CONTEXT7_API_KEYS` | Múltiplas chaves separadas por vírgula |
| 2 | Config XDG `~/.config/context7/config.toml` | TOML estruturado |
| 3 | Arquivo `.env` no CWD | `CONTEXT7_API=ctx7sk-...` |
| 4 (menor) | Chave embutida em compile-time | `CONTEXT7_API_KEYS` no ambiente de build |
**Método recomendado — via subcomando `keys add`:**
```bash
context7 keys add ctx7sk-sua-chave-aqui
context7 keys add ctx7sk-outra-chave
context7 keys list
```
O arquivo `config.toml` é criado automaticamente com `chmod 600` em:
- **Linux:** `~/.config/context7/config.toml`
- **macOS:** `~/Library/Application Support/context7/config.toml`
- **Windows:** `%APPDATA%\context7\config\config.toml`
**Via variável de ambiente (CI/CD):**
```bash
export CONTEXT7_API_KEYS="ctx7sk-chave-01,ctx7sk-chave-02,ctx7sk-chave-03"
context7 library react
```
> Obtenha sua chave em [context7.com](https://context7.com).
---
## Uso
### Estrutura geral
```
context7 [--json] <SUBCOMANDO> [ARGUMENTOS]
```
### Subcomando `library` — busca de bibliotecas
```bash
context7 library <NOME> [QUERY]
context7 lib <NOME> # alias
context7 search <NOME> # alias
```
```bash
# Busca simples
context7 library react
context7 library tokio
context7 library axum
# Com contexto semântico para ranking mais preciso
context7 library react "hooks de efeito"
context7 library axum "middleware e rotas"
context7 library tokio "canal mpsc assíncrono"
# Saída em JSON
context7 library react --json
```
Retorna: `id`, `title`, `description`, `trust_score` de cada resultado.
### Subcomando `docs` — documentação de uma biblioteca
```bash
context7 docs <LIBRARY_ID> [--query <TEXTO>] [--text] [--json]
context7 doc <LIBRARY_ID> # alias
context7 context <LIBRARY_ID> # alias
```
```bash
# Documentação básica
context7 docs /facebook/react
context7 doc /rust-lang/rust
# Com query temática
context7 docs /facebook/react --query "useEffect e ciclo de vida"
context7 docs /tokio-rs/tokio --query "channel mpsc"
context7 docs /axum-rs/axum --query "middleware tower"
# Texto plano (para pipes)
context7 docs /facebook/react --text
context7 docs /rust-lang/rust --query "ownership" --text
# JSON completo
context7 docs /facebook/react --json
```
> Use `context7 library <NOME>` primeiro para descobrir o `LIBRARY_ID` correto. A barra inicial `/` é opcional.
### Subcomando `keys` — gerenciamento de chaves de API
```bash
context7 keys add <CHAVE> # adiciona chave ao config XDG
context7 keys list # lista chaves (mascaradas)
context7 keys remove <ÍNDICE> # remove por índice 1-based
context7 keys clear [--yes] # remove todas as chaves
context7 keys path # exibe caminho do config
context7 keys import <ARQUIVO> # importa de arquivo .env legado
context7 keys export # exporta em formato .env
```
---
## Retry e rotação de chaves
Cada requisição tenta até 3 vezes com backoff exponencial (500ms → 1s → 2s). Em cada tentativa, uma chave diferente é sorteada sem reposição — garantindo distribuição uniforme entre todas as chaves disponíveis.
---
## Logs
Os logs são escritos automaticamente em dois destinos:
- **Terminal:** stderr com ANSI colors (nível `info` por padrão)
- **Arquivo:** rotação por deleção a cada execução
Caminho do arquivo de log por sistema:
- **Linux (XDG):** `~/.local/state/context7/context7.log`
- **macOS:** `~/Library/Application Support/context7/context7.log`
- **Fallback:** `logs/context7.log` no diretório atual
Nenhuma chave de API aparece nos logs — mascarada antes de qualquer escrita.
---
## Stack
| `tokio` | Runtime async multi-thread |
| `reqwest` (rustls-tls) | Cliente HTTP sem OpenSSL |
| `clap` (derive) | Parsing de CLI |
| `serde` + `serde_json` | Serialização/deserialização |
| `anyhow` + `thiserror` | Tratamento de erros |
| `tracing` + `tracing-appender` | Logs estruturados dual (terminal + arquivo) |
| `colored` | Saída colorida no terminal |
| `directories` | Caminhos XDG cross-platform |
| `toml` | Arquivo de configuração |
| `rand` | Sorteio de chaves sem reposição |
| `chrono` | Timestamps nos logs |
---
## Desenvolvimento
```bash
# Executar testes (72 testes)
cargo test
# Build release
cargo build --release
# Checar warnings
cargo clippy -- -D warnings
# Formatar código
cargo fmt
# Executar localmente
cargo run -- library react
cargo run -- docs /facebook/react --query "hooks"
cargo run -- keys list
```
---
## Licença
Licenciado sob os termos de **MIT OR Apache-2.0**, à sua escolha.
- [LICENSE-MIT](LICENSE-MIT)
- [LICENSE-APACHE](LICENSE-APACHE)
Copyright 2026 Danilo Aguiar <daniloaguiarbr@pm.me>