- name
- matter-cli
- description
- Interact with a user's Matter reading library using the Matter CLI. Use when asked to: browse inbox or reading queue, search articles by topic, get highlights or annotations, tag or archive articles, save new URLs, summarize articles, compile highlights into a digest, check reading progress, or manage the Matter library in any way. Triggers on: "my Matter library", "reading list", "inbox", "highlights", "queue", "saved articles", "reading queue", "Matter", "archive article", "tag article".
Matter CLI Skill
Setup (first time)
# Install (downloads binary directly from official GitHub releases)
# macOS arm64:
curl -fsSL https://github.com/getmatterapp/matter-cli/releases/latest/download/matter-darwin-arm64 -o ~/.matter/bin/matter && chmod +x ~/.matter/bin/matter
# macOS x86:
curl -fsSL https://github.com/getmatterapp/matter-cli/releases/latest/download/matter-darwin-x64 -o ~/.matter/bin/matter && chmod +x ~/.matter/bin/matter
# Linux arm64:
curl -fsSL https://github.com/getmatterapp/matter-cli/releases/latest/download/matter-linux-arm64 -o ~/.matter/bin/matter && chmod +x ~/.matter/bin/matter
# Linux x86:
curl -fsSL https://github.com/getmatterapp/matter-cli/releases/latest/download/matter-linux-x64 -o ~/.matter/bin/matter && chmod +x ~/.matter/bin/matter
# Add to PATH if needed
export PATH="$HOME/.matter/bin:$PATH"
# Authenticate
matter loginSource: <https://github.com/getmatterapp/matter-cli> Requires a Matter Pro subscription. Get one at <https://web.getmatter.com/settings>.
CLI binary: matter (added to PATH after install) Auth: Stored locally after matter login. Full command reference: See references/commands.md
Core Workflows
Browse Inbox
matter items list --status inbox --order inbox_position --limit 10Browse Reading Queue
matter items list --status queue --order library_position --limit 10Read / Summarize an Article
matter items get <id> --include markdownFetch markdown content, then summarize or analyze it.
Search by Topic
matter search "<topic>" --type items --limit 10Get Highlights for an Article
matter annotations list --item <item_id> --allTag an Article
matter tags list # find or confirm tag id/name first
matter tags add --item <item_id> --name "<tag_name>"Archive an Article
matter items update <id> --status archiveSave a New URL
matter items save --url "<url>" --status queueCompile Highlights Digest
- Search or list items by topic/tag
- For each item:
matter annotations list --item <id> --all - Compile highlights into structured output
Output Format
All commands return JSON by default. Use --plain for human-readable output.
⚠️ Do NOT use --all for large libraries. It streams all pages in one call and will hit rate limits mid-stream, corrupting the JSON response. Instead, paginate manually:
# First page
matter items list --status queue --order updated --limit 50 --plain
# Next page (use cursor from previous response)
matter items list --status queue --order updated --limit 50 --plain --cursor <cursor>Repeat with each returned cursor until no cursor is shown. Add sleep 5 between pages to stay within rate limits.
Rate Limits
| Operation | Limit |
|---|---|
| Read (list, get) | 120/min |
| Search | 30/min |
| Markdown (full text) | 20/min |
| Write (update, tag, archive) | 30/min |
| Save (new URLs) | 10/min |
| Burst | 5/min |
Rules for bulk operations:
- Fetching full markdown for multiple articles:
sleep 4between each call (stays under 20/min) - Running multiple searches back-to-back:
sleep 3between each (stays under 30/min) - Never fire more than 5 requests in rapid succession (burst limit)
- If you receive a
Rate limit exceeded. Retry after N secondserror: stop immediately, wait the stated seconds + 5, then resume - For research tasks across 5+ articles: fetch markdown sequentially with delays, not in parallel