Referência da CLI pinky

Todos os subcomandos do pinky, o que fazem e suas flags. Gerado a partir do --help do binário (pinky <comando> --help sempre dá a versão canônica).

Usage: pinky [OPTIONS] <COMMAND>

Flags globais (valem para todos os comandos)

FlagO que faz
--db <ruta>Índice SQLite a usar. Assume PINKY_DB se estiver definida (mesmo default que o MCP e o pinky init), assim a CLI e o agente veem a mesma base. Default brain.db.
--hash-embedUsa o embedder determinístico (sem baixar o modelo ONNX). Também é ativado com a env var PINKY_HASH_EMBED. Ideal offline/CI.
--jsonSaída em JSON, para scripts. No search além disso desativa o registro de telemetria (uso programático).
--version / -VVersão do binário.
--help / -hAjuda (do pinky ou de um subcomando).

Indexar

pinky reindex <ruta> [--project <nombre>]

Reindexa todos os .md sob <ruta>. Incremental: pula os que não mudaram (por content_hash) e apaga do índice os que já não existem. Com --project as entradas ficam no escopo project:<nombre>; sem ele, em global.

pinky reindex documentation --project sgsvp

pinky watch <ruta> [--project <nombre>]

Observa a pasta e reindexa incrementalmente ao detectar mudanças em .md. Bloqueia até Ctrl-C.

pinky watch documentation

pinky sync [--dir <carpeta>] [--push]

Sincroniza o brain global por git: git pull → reindex → (com --push) git push. A pasta default é ~/.pinky/brain; o índice vive junto ao brain (<brain>/brain.db), não o --db do CWD (para não misturar com um projeto).

pinky sync --push

Buscar

pinky search <query...> [opciones]

Busca híbrida (BM25 + vetor, fusão RRF). Filtros de metadados e rerank opt-in.

FlagO que faz
--limit <n>Quantidade de resultados (default 10).
--rerankRerank léxico leve (privilegia frase exata no título/snippet).
--project <nombre>Filtra por projeto.
--type <tipo>Filtra por tipo: gotcha | pattern | decision | diary | guide | note.
--tag <t>Filtra por tag (repetível; a entrada deve ter todas).
pinky search "timeout al cerrar el pool de postgres"
pinky search "deadlock" --project sgsvp --type gotcha --json

Salvar / preparar

pinky save --title <t> [opciones]

Salva conhecimento novo: escreve um .md com frontmatter e o indexa na hora.

FlagO que faz
--title <t>Título (obrigatório).
--body <md>Corpo markdown. Se for omitido, é lido do stdin (para pipes).
--type <tipo>gotcha | pattern | decision | diary | guide | note (default note). É normalizado e validado.
--tag <t>Etiquetas (repetível).
--project <nombre>Projeto (escopo).
--dir <carpeta>Onde escrever o .md (default documentation).
--no-fileSalva só no DB, sem .md (atenção: um reindex a apagaria).
pinky save --title "Reintento de templates" --type pattern --tag whatsapp --body "Backoff exponencial…"
echo "cuerpo largo…" | pinky save --title "Nota" --type note

pinky init [ruta]

Prepara um projeto: cria documentation/ (+ diary/), registra o MCP no .mcp.json com caminhos relativos (relocatable) e deixa um guia. Não usa embeddings.

pinky init

Manter (saúde do conhecimento)

pinky dedup [--threshold <0..1>]

Lista pares de entradas quase-duplicadas (similaridade cosseno > limiar, default 0.9). Não apaga nada — a decisão de mesclar é manual.

pinky stale [--days <n>]

Lista entradas com last_verified mais antigo que <n> dias (default 180), ou sem data, da mais antiga para a mais nova. Não usa embeddings.

pinky telemetry

Mostra as entradas mais recuperadas (título + vezes + última vez) e as que nunca foram usadas (candidatas a poda). Não usa embeddings.

pinky lint [carpeta]

Valida os .md: reporta frontmatter que se degradaria em silêncio (YAML inválido, type/datas mal formadas). Sai ≠0 se houver erros → apto para CI.

pinky evergreen <archivo>

Valida que um doc (p. ex. CLAUDE.md) seja evergreen: marca dados voláteis (nº de linha, LOC, archivo:línea). Sai ≠0 se encontrar algum.

Escaneia uma árvore de código buscando marcadores // Brain: <slug> e popula os backlinks do repo (default default).

Lista o código (archivo:línea) que referencia um <slug>.

pinky backlinks scan ./src --repo miapp
pinky backlinks of pool-postgres

Rollups de diary

pinky rollup <dir> [--period week|month] [--out <archivo>]

Agrega os diaries (YYYY-MM-DD.md) de uma pasta em um resumo markdown determinístico (sem LLM). --period default week; --out escreve em arquivo em vez de stdout.

pinky rollup documentation/diary --period month --out RESUMEN.md

Diagnóstico

pinky stats

Quantidade de entradas e chunks indexados.

pinky doctor

Checagem do ambiente: versão do binário, sqlite-vec, versão de schema, entradas/chunks, e modelo do índice vs. embedder ativo (avisa se não coincidem). Tolera que o índice não exista (te diz o que rodar). Com --json, apto para monitoramento.

Qualidade do retrieval

pinky eval <golden.json> [--k <n>] [--min-hit-rate <x>] [--min-mrr <x>]

Mede a qualidade do retrieval contra um golden set de queries douradas: reporta hit@k e MRR. Com --min-hit-rate/--min-mrr, sai com código 1 se cair abaixo do limiar → trava o build em CI diante de uma regressão.

pinky eval testdata/golden.json --min-hit-rate 0.95 --min-mrr 0.9

Utilitários

pinky completions <bash|zsh|fish>

Imprime o script de autocompletar para o seu shell.

pinky completions zsh > ~/.zfunc/_pinky
As três peças compartilham o mesmo índice: CLI pinky (isto), MCP pinky-mcp (para o agente: brain_search/brain_save/brain_stats) e hooks pinky-hooks (Claude Code). Ver HOW-IT-WORKS.md e CONFIGURATION.md.