SwipeVault CLI

Acesse seu SwipeVault direto do terminal. Feito para agentes de IA (Claude Code, Cursor, Codex) — e para você.

Instalação

npm install -g swipevault

Ou, durante desenvolvimento:

cd packages/cli
npm install
npm link
swipevault --version

Requer Node.js 18+.

Quickstart

1. Login

swipevault auth login

Abre o browser no SwipeVault, você autoriza o acesso, e a chave é salva em ~/.swipevault/config.json com permissão 0600.

Modo CI/CD (sem browser):

swipevault auth login --token sk_live_...

2. Verificar autenticação

swipevault auth status
# ✓ Autenticado
#   User ID: ...
#   Key prefix: sk_live_abcd...wxyz (fonte: config)
#   Plano: free

3. Setup de skills em IDEs

swipevault init

Detecta Claude Code, Cursor, Codex e Copilot no diretório atual e instala skill files para cada um.

Comandos

| Comando | Descrição | |---------|-----------| | swipevault | Banner + versão | | swipevault --version / version | Versão | | swipevault auth login | Login (Device Code Flow ou --token) | | swipevault auth status | Verifica credenciais | | swipevault auth whoami | Alias de status | | swipevault auth logout | Remove credenciais locais | | swipevault init | Wizard de setup (auth + skills) | | swipevault health | Smoke test do gateway (latência + auth) | | swipevault config show | Mostra config (api_key mascarada) | | swipevault config get <key> | Imprime valor (útil em scripts) | | swipevault config set <key> <value> | Atualiza config (só api_url; use - pra stdin) | | swipevault config reset | Deleta config file (confirmação) | | swipevault config path | Caminho do config file |

Swipe (domínio principal):

| Comando | Descrição | |---------|-----------| | swipevault swipe get <id> | Detalha um swipe (--include transcription/translation/body/...) | | swipevault swipe search <query> | Busca fulltext com ~25 filtros de taxonomia | | swipevault swipe list | Lista sem busca (mesmos filtros do search) | | swipevault swipe stats | Estatísticas do vault | | swipevault swipe transcription <id> | Transcrição (+ --block lead,proof --with-comments) | | swipevault swipe comments <id> | Comments | | swipevault swipe translation <id> | Tradução | | swipevault swipe debrief <id> | Debrief | | swipevault swipe download <id> -o ./ | Baixa o arquivo binário |

Filtros de taxonomia disponíveis em search e list:

--copy-type, --file-type, --niche-id, --niche, --market, --tag, --source-platform, --transcription-status, --production-format-id, --solution-format-id, --lead-type-primary-id, --teaser-category-id, --teaser-type-primary-id, --teaser-angle-primary-id, --awareness-level-id, --sophistication-stage-id, --emotional-pole-id, --emotional-benefit-id, --nationality-id, --language, --date-from, --date-to, --favorite, --has-transcription, --has-translation, --has-dismantle, --has-comments, --has-debrief

Flags de ordenação e paginação: --sort newest|oldest|most_enriched|least_enriched, --limit, --cursor, --keyword, --with-description

Output formats: -o json|table|csv|yaml|raw (auto-detect: table em TTY, json em pipe)

Collection + Guide (read-only):

| Comando | Descrição | |---------|-----------| | swipevault collection list | Lista coleções (--is-favorite, --has-guide) | | swipevault collection show <id-or-name> | Resolve por UUID ou nome; --include items,guide | | swipevault guide show <id-or-name> | Mostra o Collection Guide (501 tolerado até Wave 4) |

Resolução por nome: swipevault collection show "Hooks de Urgência" detecta se é UUID (regex) ou busca por nome. Nome ambíguo → erro orientando UUID.

501 tolerado: --include-guide e guide show retornam warning gracioso (exit 0) até a Wave 4 (Story 8.20) implementar o endpoint.

Exit codes

| Código | Significado | |--------|-------------| | 0 | Sucesso | | 1 | Erro genérico | | 2 | Não autenticado / 401 | | 3 | Erro de rede / timeout | | 4 | Recurso não encontrado (404) | | 5 | Rate limit (429) |

Variáveis de ambiente

| Variável | Uso | |----------|-----| | SWIPEVAULT_API_KEY | Override de autenticação (prioridade: flag > env > config) | | SWIPEVAULT_API_URL | Override da API URL (default: https://vault.swipemind.com.br) | | SWIPEVAULT_CONFIG_DIR | Override do diretório de config (default: ~/.swipevault/) | | NO_COLOR | Desativa cores ANSI | | NO_UNICODE | Usa banner ASCII simples (sem box drawing) |

Output: TTY vs Pipe

• Terminal interativo (TTY): tabelas coloridas, banner ASCII, spinners
• Pipe / redirect: JSON em stdout, erros em JSON no stderr

swipevault auth status          # output colorido
swipevault auth status | jq .   # JSON

Desenvolvimento

npm install
npm test           # node --test nativo
node bin/swipevault.mjs --help

Segurança

• Config file ~/.swipevault/config.json tem permissão 0600 (POSIX)
• API keys nunca aparecem em logs — sempre mascaradas via redactKey()
• Modo --token <key> pode vazar via ps aux — prefira SWIPEVAULT_API_KEY env var ou auth login

Licença

UNLICENSED — parte do ecossistema SwipeMind / Black Zontik.