context7-cli 0.2.8

# Cross-Platform Guide — context7-cli

**EN:** This guide covers platform-specific behavior, known quirks, and installation notes for context7-cli on Windows, macOS, and Linux distributions.

**PT:** Este guia cobre o comportamento específico por plataforma, particularidades conhecidas e instruções de instalação do context7-cli no Windows, macOS e distribuições Linux.

---

## Windows — UTF-8 Console Setup

**EN:** Since v0.2.4, context7-cli automatically configures the Windows console to UTF-8 (code page 65001) at startup. This ensures that accented characters, special symbols, and bilingual output (EN/PT) render correctly in `cmd.exe`, PowerShell, and Windows Terminal.

**PT:** Desde a v0.2.4, o context7-cli configura automaticamente o console do Windows para UTF-8 (code page 65001) na inicialização. Isso garante que caracteres acentuados, símbolos especiais e a saída bilíngue (EN/PT) sejam exibidos corretamente no `cmd.exe`, PowerShell e Windows Terminal.

### How it works / Como funciona

```rust
// src/main.rs — chamada no startup do main() antes de qualquer I/O
#[cfg(windows)]
configurar_console_utf8();
```

Internally / Internamente:
- `SetConsoleOutputCP(65001)` — sets output code page to UTF-8
- `SetConsoleCP(65001)` — sets input code page to UTF-8
- `colored::control::set_virtual_terminal(true)` — enables ANSI escape sequences for colored output

**EN:** If `set_virtual_terminal` fails (very old `cmd.exe` without Virtual Terminal Processing), colors are automatically disabled to prevent raw escape sequences from appearing.

**PT:** Se `set_virtual_terminal` falhar (cmd.exe muito antigo sem Virtual Terminal Processing), as cores são desabilitadas automaticamente para evitar que escape sequences brutas sejam exibidas.

### Configuration path / Caminho de configuração

```
%APPDATA%\context7\config\config.toml
```

Example / Exemplo:

```
C:\Users\YourName\AppData\Roaming\context7\config\config.toml
```

### Override via `CONTEXT7_HOME`

**EN:** Set `CONTEXT7_HOME` to use a custom directory. Path traversal (`..`) is rejected for security.

**PT:** Defina `CONTEXT7_HOME` para usar um diretório personalizado. Path traversal (`..`) é rejeitado por segurança.

```powershell
$env:CONTEXT7_HOME = "C:\MyConfig"
context7 keys list
```

---

## macOS — Gatekeeper and Code Signing

### Adhoc signing vs Developer ID / Assinatura adhoc vs Developer ID

**EN:** The GitHub Actions release workflow produces a Universal Binary (Intel x86_64 + Apple Silicon arm64, combined via `lipo`). The signing behavior depends on whether Apple Developer secrets are configured in the repository:

**PT:** O workflow de release do GitHub Actions produz um Universal Binary (Intel x86_64 + Apple Silicon arm64, combinados via `lipo`). O comportamento de assinatura depende de os secrets do Apple Developer estarem configurados no repositório:

| Condition / Condição | Signing / Assinatura | Notarization / Notarização |
|---|---|---|
| `APPLE_TEAM_ID` secret set | Developer ID (full) | Apple notarytool ✓ |
| `APPLE_TEAM_ID` empty/absent | Adhoc (`codesign --sign -`) | Not notarized |

### First-run Gatekeeper warning / Aviso Gatekeeper na primeira execução

**EN:** If the binary is downloaded from GitHub Releases (not notarized), macOS Gatekeeper may block execution with the message _"context7 cannot be opened because it is from an unidentified developer"_. To allow execution:

**PT:** Se o binário for baixado dos GitHub Releases (sem notarização), o macOS Gatekeeper pode bloquear a execução com a mensagem _"context7 não pode ser aberto porque é de um desenvolvedor não identificado"_. Para permitir a execução:

```bash
# Remove the quarantine attribute set by Gatekeeper
# Remove o atributo de quarentena definido pelo Gatekeeper
xattr -d com.apple.quarantine context7

# Make executable if needed / Tornar executável se necessário
chmod +x context7

# Verify the binary is a valid Universal Binary
# Verificar que o binário é um Universal Binary válido
lipo -info context7
# Expected output: Architectures in the fat file: context7 are: x86_64 arm64
```

**EN:** Alternatively, right-click the binary in Finder → Open → Open (bypasses Gatekeeper for that file).

**PT:** Alternativamente, clique com o botão direito no binário no Finder → Abrir → Abrir (ignora o Gatekeeper para esse arquivo).

### Install via cargo / Instalação via cargo

**EN:** The recommended installation method avoids Gatekeeper entirely:

**PT:** O método de instalação recomendado evita o Gatekeeper completamente:

```bash
cargo install context7-cli
```

**EN:** Binaries compiled locally are not subject to Gatekeeper quarantine.

**PT:** Binários compilados localmente não estão sujeitos à quarentena do Gatekeeper.

### Configuration path / Caminho de configuração

```
~/Library/Application Support/context7/config.toml
```

### Override via `CONTEXT7_HOME`

```bash
export CONTEXT7_HOME="$HOME/.myconfig"
context7 keys list
```

---

## Linux — Distribution Guide

### Standard install via cargo / Instalação padrão via cargo

**EN:** Works on any Linux distribution with a glibc ≥ 2.31 (standard since Ubuntu 20.04+, Debian 11+, Fedora 32+, Arch, etc.):

**PT:** Funciona em qualquer distribuição Linux com glibc ≥ 2.31 (padrão desde Ubuntu 20.04+, Debian 11+, Fedora 32+, Arch, etc.):

```bash
cargo install context7-cli
```

**EN:** The binary is installed to `~/.cargo/bin/context7`. Add `~/.cargo/bin` to your `PATH` if not already present.

**PT:** O binário é instalado em `~/.cargo/bin/context7`. Adicione `~/.cargo/bin` ao seu `PATH` se ainda não estiver presente.

### Configuration path (XDG) / Caminho de configuração (XDG)

```
~/.config/context7/config.toml
```

**EN:** Follows the XDG Base Directory Specification via the `directories` crate. Respects `$XDG_CONFIG_HOME` if set.

**PT:** Segue a XDG Base Directory Specification via o crate `directories`. Respeita `$XDG_CONFIG_HOME` se definido.

### Alpine Linux / musl

**EN:** The standard glibc binary does **not** run on Alpine Linux (which uses musl libc). Use the static musl binary from the GitHub Releases page:

**PT:** O binário glibc padrão **não** funciona no Alpine Linux (que usa musl libc). Use o binário musl estático da página de GitHub Releases:

```bash
# Download the musl static binary / Baixar o binário musl estático
curl -L https://github.com/daniloaguiarbr/context7-cli/releases/latest/download/context7-x86_64-unknown-linux-musl.tar.gz \
  | tar xz

# Make executable and move to PATH / Tornar executável e mover para PATH
chmod +x context7
mv context7 /usr/local/bin/
```

**EN:** The musl binary is fully static — no shared library dependencies.

**PT:** O binário musl é completamente estático — sem dependências de bibliotecas compartilhadas.

### NixOS / GNU Guix

**EN:** A `flake.nix` is not included in v0.2.8. The recommended approach for NixOS is to use `cargo install` with a Rust toolchain from nixpkgs, or to package it locally with a derivation. Community flakes may be available.

**PT:** Um `flake.nix` não está incluído na v0.2.8. A abordagem recomendada para NixOS é usar `cargo install` com uma toolchain Rust do nixpkgs, ou empacotá-lo localmente com uma derivação. Flakes da comunidade podem estar disponíveis.

### Flatpak

**EN:** The GitHub Actions release workflow builds a Flatpak bundle artifact. Install from a local `.flatpak` file:

**PT:** O workflow de release do GitHub Actions gera um artefato Flatpak bundle. Instalar a partir de um arquivo `.flatpak` local:

```bash
# Add Flathub remote (if not already added) / Adicionar remote Flathub (se não adicionado)
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install the Flatpak bundle / Instalar o bundle Flatpak
flatpak install --user context7-cli.flatpak

# Run / Executar
flatpak run br.com.daniloaguiar.context7-cli library react
```

**EN:** The Flatpak runs in a sandbox with `--share=network` only — no filesystem access beyond the user home. Configuration is stored inside the Flatpak sandbox data directory.

**PT:** O Flatpak roda em sandbox com apenas `--share=network` — sem acesso ao filesystem além do home do usuário. A configuração é armazenada dentro do diretório de dados do sandbox do Flatpak.

**Build details / Detalhes do build:**

| Field / Campo | Value / Valor |
|---|---|
| `app-id` | `br.com.daniloaguiar.context7-cli` |
| `runtime` | `org.freedesktop.Platform` |
| `runtime-version` | `24.08` |
| `sdk-extension` | `org.freedesktop.Sdk.Extension.rust-stable` |
| `finish-args` | `--share=network` |

### Snap

**EN:** The GitHub Actions release workflow builds a Snap artifact. Install from a local `.snap` file:

**PT:** O workflow de release do GitHub Actions gera um artefato Snap. Instalar a partir de um arquivo `.snap` local:

```bash
# Install from local file (unsigned) / Instalar a partir de arquivo local (sem assinatura)
sudo snap install context7-cli_*.snap --dangerous

# Set up alias / Configurar alias
sudo snap alias context7-cli.context7 context7

# Run / Executar
context7 library react
```

**EN:** If published to the Snap Store in the future:

**PT:** Se publicado no Snap Store no futuro:

```bash
sudo snap install context7-cli
```

**Snap configuration details / Detalhes de configuração do Snap:**

| Field / Campo | Value / Valor |
|---|---|
| `base` | `core24` |
| `confinement` | `strict` |
| `grade` | `stable` |
| `plugs` | `network`, `home` |
| `architectures` | `amd64`, `arm64` |

### SELinux / AppArmor

**EN:** No special policy is required. context7-cli is a user-space CLI that:
- Makes outbound HTTPS connections to `api.context7.com`
- Reads/writes configuration in `~/.config/context7/` (or `$XDG_CONFIG_HOME`)
- Has no elevated privileges, no setuid/setgid, no kernel interfaces

**PT:** Nenhuma política especial é necessária. O context7-cli é uma CLI user-space que:
- Faz conexões HTTPS de saída para `api.context7.com`
- Lê/escreve configuração em `~/.config/context7/` (ou `$XDG_CONFIG_HOME`)
- Não possui privilégios elevados, sem setuid/setgid, sem interfaces com o kernel

**EN:** Standard SELinux `unconfined_u:unconfined_r:unconfined_t` context is sufficient. AppArmor does not restrict user binaries by default on Ubuntu.

**PT:** O contexto SELinux padrão `unconfined_u:unconfined_r:unconfined_t` é suficiente. O AppArmor não restringe binários de usuário por padrão no Ubuntu.

---

## Summary Table / Tabela Resumo

| Platform / Plataforma | Config Path | UTF-8 Auto | Notes / Notas |
|---|---|---|---|
| Windows (cmd/PS) | `%APPDATA%\context7\config\config.toml` | Yes (v0.2.4+) | ANSI auto-detected |
| macOS | `~/Library/Application Support/context7/config.toml` | N/A | `xattr` if Gatekeeper blocks |
| Linux (glibc) | `~/.config/context7/config.toml` | N/A | XDG compliant |
| Alpine (musl) | `~/.config/context7/config.toml` | N/A | Use musl static binary |
| Linux Flatpak | Sandbox data dir | N/A | `--share=network` only |
| Linux Snap | Snap data dir | N/A | `strict` confinement |

**EN:** All platforms respect the `CONTEXT7_HOME` environment variable as a universal config path override. Path traversal (`..`) is always rejected.

**PT:** Todas as plataformas respeitam a variável de ambiente `CONTEXT7_HOME` como um override universal do caminho de configuração. Path traversal (`..`) é sempre rejeitado.