scribe-cli

name

scribe-cli

description

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.

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: https://getscribe.dev/setup.md. 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 <kb> --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 <path>
Approve/ignore discovered repos	scribe projects review
Absorb a local file or URL	scribe absorb <file> / scribe ingest url <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 <cmd> --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 <path> 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).
• https://getscribe.dev/setup.md — 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.