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 login

Source:

Requires a Matter Pro subscription. Get one at .

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 10

Browse Reading Queue

matter items list --status queue --order library_position --limit 10

Read / Summarize an Article

matter items get <id> --include markdown

Fetch markdown content, then summarize or analyze it.

Search by Topic

matter search "<topic>" --type items --limit 10

Get Highlights for an Article

matter annotations list --item <item_id> --all

Tag 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 archive

Save a New URL

matter items save --url "<url>" --status queue

Compile Highlights Digest

1. Search or list items by topic/tag
2. For each item: matter annotations list --item --all
3. 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

Rules for bulk operations:

• Fetching full markdown for multiple articles: sleep 4 between each call (stays under 20/min)
• Running multiple searches back-to-back: sleep 3 between 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 seconds error: stop immediately, wait the stated seconds + 5, then resume
• For research tasks across 5+ articles: fetch markdown sequentially with delays, not in parallel