Matter CLI

Manage and interact with your Matter reading library: browse, search, save, tag, archive, highlight, summarize, and track reading progress via Matter CLI.

Matter CLI Skill

Setup (first time)

bash

# 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: 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

bash

matter items list --status inbox --order inbox_position --limit 10

Browse Reading Queue

bash

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

Read / Summarize an Article

bash

matter items get <id> --include markdown

Fetch markdown content, then summarize or analyze it.

Search by Topic

bash

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

Get Highlights for an Article

bash

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

Tag an Article

bash

matter tags list   # find or confirm tag id/name first
matter tags add --item <item_id> --name "<tag_name>"

Archive an Article

bash

matter items update <id> --status archive

Save a New URL

bash

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 <id> --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:

bash

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