CLI usage guide

Common commands, stats, writes with —apply, MCP, and updates

Command style

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

Full list: starcat help and the README.

Common read-only commands

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

stats is a local read-only aggregate (Stars / knowledge base / AI tokens / RAG, etc.) for quick inspection.

Writes (dry-run by default)

# Preview only — no write
printf '%s' 'A private note' | starcat repo note set owner/repo

# Actually write
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

If write permission switches are off in the app, --apply still fails. See MCP settings.

MCP

starcat mcp

Register as an MCP server in Cursor / Claude Code / Codex: command=starcat, args=["mcp"].
Protocol messages use stdout only; diagnostics go to stderr.

Updates

starcat update
# or
brew update && brew upgrade starcat

Interactive terminals may prompt for updates at most about once per day; starcat mcp in a pipe does not spam update notices.

Related

• Installation and pairing
• Skill