# Scribe CLI > Set up and operate the scribe CLI — install/init personal or team KBs, diagnose with doctor/status, run sync/extraction, manage cron and Full Disk Access, and pick the right command for a maintenance goal. Use when the user wants to install or run scribe, asks which scribe command or init/team flags to use, says their KB is stale/empty or extraction/sync stopped, or is reading `scribe doctor`/`scribe status` output. For authoring KB content use scribe-kb; for the `scribe lint` content-quality queue use scribe-kb-tidy. - Skill: `oliver-kriska/scribe-cli` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add oliver-kriska/scribe-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/oliver-kriska/scribe-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: oliver-kriska (https://skillmd.com/u/oliver-kriska) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/oliver-kriska/scribe-cli --- # scribe CLI — operations agent skill `scribe` is a single-binary Go CLI that runs a knowledge-base pipeline: discover repos → extract knowledge → mine agent sessions → absorb URLs → lint → reindex with qmd. It normally runs unattended on cron. This skill is for **driving the CLI by hand** — diagnosing health, running a step manually, and choosing the right command for a goal. Two sibling skills own the other halves and this skill routes to them: - **scribe-kb** — authoring/searching KB *content* (articles, drop files, qmd). - **scribe-kb-tidy** — working the `scribe lint` content-quality queue (split bloated, archive rolling, merge thin/self-named-dirs). ## Installation or bootstrap requests For zero-to-running setup, read the public, prompt-compatible runbook first: . It has separate command sequences for a personal Anthropic KB, local Ollama, a hosted OpenAI-compatible provider, the team owner, each team member, a second KB on one machine, and Linux cron. Follow one profile rather than mixing flags. Key distinctions the short command map cannot express: - Fresh/default KBs use `scribe init --path --bind`; `--bind` is what installs the machine-global Claude/Codex/Amp handshake. - Only the team owner uses `--team`, `--kb-name`, `--allow`, and `--provider`. Members clone, `cd` into the checkout, then run `scribe init --bind --yes`. - Quote a shared tilde path (`--allow '~/work'`) so the shell does not commit the owner's absolute home path. - Discover and approve sources before extraction: `scribe sync --discover`, then `scribe projects review`. - The safe cost/scope preflight is `scribe sync --dry-run --estimate`. Ask before the first real sync when it may spend tokens. - `scribe skill install` is post-bootstrap assistance. It does not install the binary/dependencies, choose personal versus team mode, bind the handshake, approve sources, install cron, or verify the provider. ## Golden rule: diagnose read-only before you act Always start with the two read-only commands. They never write and never call an LLM, so they are safe to run anytime: ``` scribe doctor # deps, config, cron, state, run-freshness, errors, ledgers — read-only health scribe status # scoreboard: raw-by-density, absorb/contextualize progress, backlog, last sync ``` Read the output first, then run the *one* command it points you at. `doctor` prints a FAIL/WARN per check and ends with the `status` scoreboard; most WARN lines already name the command that clears them. See `references/TROUBLESHOOT.md` for how to read each section. ## Respect the daemon (the lock rule) scribe runs on the user's cron. Two commands take a **machine-wide lock shared with that daemon**: - `scribe sync` — the full pipeline (discover → extract → mine → absorb → reindex) - `scribe dream` — weekly/`--hot` memory consolidation Run them manually **only** when you know cron isn't mid-run, run **one at a time**, and **never background them** — a stray backgrounded `sync`/`dream` blocks the real cron job. Everything else here is safe to run interactively. ## Goal → command (quick map) | The user wants to… | Command | |---|---| | Check if scribe is healthy | `scribe doctor` | | See what's pending / backlog | `scribe status` | | Run the whole pipeline now | `scribe sync` (mind the lock rule) | | Just mine agent sessions | `scribe sync --sessions` | | Estimate token cost before syncing | `scribe sync --dry-run --estimate` | | Score unprocessed sessions by value | `scribe triage` | | Enroll a repo for extraction | `scribe projects add ` | | Approve/ignore discovered repos | `scribe projects review` | | Absorb a local file or URL | `scribe absorb ` / `scribe ingest url --absorb` | | Fix frontmatter errors | `scribe lint --fix` | | Work the lint content queue | → hand off to the **scribe-kb-tidy** skill | | Author/search KB content | → hand off to the **scribe-kb** skill | | Check LLM spend | `scribe cost` | | Install / check the background jobs | `scribe cron install` / `scribe cron status` — on Linux, install prints a block to paste into `crontab -e` and status reports whether it landed | | Restore chat.db access (macOS) | `scribe fda` | The full command surface (every subcommand, grouped) is in `references/COMMANDS.md`. When unsure which command fits, read that first rather than guessing flags. ## After upgrading the binary Official macOS releases are Developer ID signed, so FDA survives an in-place replacement at the same registered path. Homebrew also moves the executable to a new versioned Cellar path that TCC records separately, so run `scribe fda` after `brew upgrade`. Source-built installs need a re-grant when unsigned; `make install` signs automatically when a Developer ID Application identity is available. Confirm with `scribe doctor` (the `deps` section shows the chat.db/FDA check), and verify the live binary first with `which scribe` and `scribe --version`. ## Safety rules - **Read-only first.** `doctor`/`status` before any mutating command. Don't run `sync`/`dream` to "see what happens" — respect the lock rule. - **Let the output pick the command.** Don't invent remediation; most WARNs name their fix. If unsure, `scribe --help`. - **Don't fabricate KB content** to make a check pass — that's the daemon's job and corrupts provenance. Fix configuration/state, not the knowledge. - **Scope with `-C ` or `SCRIBE_KB`** when the user has more than one KB; don't assume the cwd is the intended KB (doctor/status print which KB they hit). - **Commit is the user's call.** The KB auto-commits on cron; run `scribe commit` explicitly only when asked. ## What NOT to do - **Don't background `scribe sync`/`scribe dream`** or run two at once. - **Don't run content authoring or lint-queue work here** — route to scribe-kb / scribe-kb-tidy so each skill stays one job. - **Don't edit `scribe.yaml` blind** — for team KBs, sensitive-key changes go through `scribe config diff` / `scribe config trust`. ## References - `references/COMMANDS.md` — the full subcommand map, grouped (core / content / quality / maintenance / machine). - `references/TROUBLESHOOT.md` — symptom → doctor section → fix, for the common failure modes (extraction stalled, cron off, FDA lost, ollama down, qmd not indexed, lint errors). - — zero-to-running personal/team setup and verification, including the exact init flags. - The **scribe-kb** and **scribe-kb-tidy** skills (installed alongside) for content authoring and the lint content queue respectively.