CLI usage

Read-only JSON, writes dry-run until —apply, MCP stdio, updates

Purpose

After pairing, search Stars, change tags / status / notes, or hand starcat mcp to an external agent. Writes do not persist until --apply. If the app’s write switches are off, --apply still fails.

Terminal starcat stats / repo search, plus MCP write toggles

Screenshot TODO · images/screenshots/cli/usage.webp

Command style

Kind	Output	Examples
Ops / friendly	Text	help doctor stats pair
Data	JSON	capabilities repo tags

Full list: starcat help and the README.

starcat capabilities
starcat stats
starcat stats ai --range 30d
starcat stats knowledge

starcat repo search "local RAG" --scope starred --limit 20
starcat repo context owner/repo
starcat repo readme owner/repo
starcat repo summary owner/repo
starcat tags list

printf '%s' 'A private note' | starcat repo note set owner/repo
printf '%s' 'A private note' | starcat repo note set owner/repo --apply
starcat repo tags add owner/repo Swift macOS --apply
starcat repo status set owner/repo using --apply

starcat mcp

Register in Cursor / Claude Code / Codex: command=starcat, args=["mcp"]. Protocol on stdout; diagnostics on stderr.

starcat update
# or
brew update && brew upgrade starcat

Interactive terminals hint about a new version at most about once a day. starcat mcp pipes do not print update noise.

Notes

The CLI does not open SQLite. See MCP and Skill.