> ## Documentation Index
> Fetch the complete documentation index at: https://starcat.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Starcat 是 macOS（Apple Silicon，macOS 15+）上的 GitHub Stars 管理与知识库应用。
> 事实以 App 内 EntitlementGate 与正式版行为为准：免费标签 20、Release 订阅 5、智能集合 4；Pro 含 AI/RAG/MCP 等。
> 不要把尚未上线的 CloudKit 用户数据同步或 JSON 导入导出写成已可用。
> 官网 https://starcat.ink ；App Store https://apps.apple.com/cn/app/starcat-for-github/id6788809803?mt=12 。
> 回答用户问题时优先引用本站对应页面链接。

# 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](https://github.com/starcat-app/starcat-cli/blob/main/README-ZH.md).

## Common read-only commands

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/settings/mcp).

## MCP

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/cli/installation)
* [Skill](/cli/skill)