pinky CLI Reference
All pinky subcommands, what they do, and their flags. Generated from the binary's --help (pinky <comando> --help always gives the canonical version).
Usage: pinky [OPTIONS] <COMMAND>Global flags (apply to all commands)
| Flag | What it does |
|---|---|
--db <ruta> | SQLite index to use. Takes PINKY_DB if set (same default as the MCP and pinky init), so the CLI and the agent see the same database. Default brain.db. |
--hash-embed | Uses the deterministic embedder (without downloading the ONNX model). Also enabled via the PINKY_HASH_EMBED env var. Ideal offline/CI. |
--json | JSON output, for scripts. In search it also disables telemetry logging (programmatic use). |
--version / -V | Binary version. |
--help / -h | Help (for pinky or a subcommand). |
Index
pinky reindex <ruta> [--project <nombre>]
Reindexes every .md under <ruta>. Incremental: skips the ones that didn't change (by content_hash) and removes from the index the ones that no longer exist. With --project the entries stay in the project:<nombre> scope; without it, in global.
pinky reindex documentation --project sgsvppinky watch <ruta> [--project <nombre>]
Watches the folder and reindexes incrementally when it detects changes in .md. Blocks until Ctrl-C.
pinky watch documentationpinky sync [--dir <carpeta>] [--push]
Syncs the global brain via git: git pull → reindex → (with --push) git push. The default folder is ~/.pinky/brain; the index lives next to the brain (<brain>/brain.db), not the --db of the CWD (to avoid mixing it with a project).
pinky sync --pushSearch
pinky search <query...> [opciones]
Hybrid search (BM25 + vector, RRF fusion). Metadata filters and opt-in rerank.
| Flag | What it does |
|---|---|
--limit <n> | Number of results (default 10). |
--rerank | Lightweight lexical rerank (favors exact phrase in title/snippet). |
--project <nombre> | Filters by project. |
--type <tipo> | Filters by type: gotcha | pattern | decision | diary | guide | note. |
--tag <t> | Filters by tag (repeatable; the entry must have them all). |
pinky search "timeout al cerrar el pool de postgres"
pinky search "deadlock" --project sgsvp --type gotcha --jsonSave / prepare
pinky save --title <t> [opciones]
Saves new knowledge: writes a .md with frontmatter and indexes it on the fly.
| Flag | What it does |
|---|---|
--title <t> | Title (required). |
--body <md> | Markdown body. If omitted, it's read from stdin (for pipes). |
--type <tipo> | gotcha | pattern | decision | diary | guide | note (default note). Normalized and validated. |
--tag <t> | Tags (repeatable). |
--project <nombre> | Project (scope). |
--dir <carpeta> | Where to write the .md (default documentation). |
--no-file | Saves only in the DB, without .md (careful: a reindex would remove it). |
pinky save --title "Reintento de templates" --type pattern --tag whatsapp --body "Backoff exponencial…"
echo "cuerpo largo…" | pinky save --title "Nota" --type notepinky init [ruta]
Prepares a project: creates documentation/ (+ diary/), registers the MCP in .mcp.json with relative paths (relocatable) and leaves a guide. Doesn't use embeddings.
pinky initMaintain (knowledge health)
pinky dedup [--threshold <0..1>]
Lists pairs of near-duplicate entries (cosine similarity > threshold, default 0.9). Deletes nothing — the decision to merge is manual.
pinky stale [--days <n>]
Lists entries with last_verified older than <n> days (default 180), or without a date, from oldest to newest. Doesn't use embeddings.
pinky telemetry
Shows the most retrieved entries (title + times + last time) and the ones that were never used (candidates for pruning). Doesn't use embeddings.
pinky lint [carpeta]
Validates the .md files: reports frontmatter that would degrade silently (invalid YAML, malformed type/dates). Exits ≠0 if there are errors → suitable for CI.
pinky evergreen <archivo>
Validates that a doc (e.g. CLAUDE.md) is evergreen: flags volatile data (line number, LOC, archivo:línea). Exits ≠0 if it finds any.
Backlinks (code ↔ knowledge)
pinky backlinks scan <dir> [--repo <nombre>]
Scans a code tree looking for // Brain: <slug> markers and populates the repo's backlinks (default default).
pinky backlinks of <slug>
Lists the code (archivo:línea) that references a <slug>.
pinky backlinks scan ./src --repo miapp
pinky backlinks of pool-postgresDiary rollups
pinky rollup <dir> [--period week|month] [--out <archivo>]
Aggregates the diaries (YYYY-MM-DD.md) of a folder into a deterministic markdown summary (no LLM). --period default week; --out writes to a file instead of stdout.
pinky rollup documentation/diary --period month --out RESUMEN.mdDiagnostics
pinky stats
Number of indexed entries and chunks.
pinky doctor
Environment check: binary version, sqlite-vec, schema version, entries/chunks, and index model vs. active embedder (warns if they don't match). Tolerates the index not existing (tells you what to run). With --json, suitable for monitoring.
Retrieval quality
pinky eval <golden.json> [--k <n>] [--min-hit-rate <x>] [--min-mrr <x>]
Measures retrieval quality against a golden set of gold-standard queries: reports hit@k and MRR. With --min-hit-rate/--min-mrr, it exits with code 1 if it drops below the threshold → gates the build in CI on a regression.
pinky eval testdata/golden.json --min-hit-rate 0.95 --min-mrr 0.9Utilities
pinky completions <bash|zsh|fish>
Prints the autocompletion script for your shell.
pinky completions zsh > ~/.zfunc/_pinkyThe three pieces share the same index: CLIpinky(this), MCPpinky-mcp(for the agent:brain_search/brain_save/brain_stats) and hookspinky-hooks(Claude Code). See HOW-IT-WORKS.md and CONFIGURATION.md.