Matter CLI (matter)

CLI + TUI for the Matter reading app. JSON-first, built for agents. Invoke as matter (installed at ~/.matter/bin/matter).

If command -v matter is empty, add its dir to PATH: export PATH="$HOME/.matter/bin:$PATH".

Auth: already configured via ~/.config/matter/config.json. Re-auth only if commands 401: matter login <mat_token> (browser copy) or echo "$MATTER_TOKEN" | matter login. Never print or store the token.

Rate limits: read 120/min, write 30/min, save 10/min. --all on a large library can burn the read budget — prefer --limit + cursor unless the user needs everything.

Quick reference

IDs are prefixed: items itm_…, tags tag_…, annotations ann_…. Get them from a list before acting.

items

matter items <list|get|save|update|delete>

list — envelope: { object:"list", results:[…], has_more, next_cursor }.

get <id> — --include markdown to fetch the article body (omit for metadata only; body is the expensive field).

save — --url <url> (required), --status queue|archive (default queue). Returns immediately with processing_status:"processing" and title:null; the item fetches asynchronously. The returned id 404s ("The requested resource was not found.") on an immediate get, and the item isn't in list yet. Don't re-get it right away — if you need the settled item (e.g. to tag it), poll items list and match on url until it appears, then use that id. A delete issued while still processing may not stick.

update <id> — --status <s>, --favorite true|false, --progress <0.0-1.0>.

delete <id> — permanent. Confirm intent first.

annotations (highlights)

matter annotations <list|get|update|delete>

• list --item <id> [--all] — highlights + notes on an item.
• get <id> — single annotation.
• update <id> --note "<text>" — set/replace the note on a highlight.
• delete <id> — permanent. Confirm intent.

tags

matter tags <list|add|remove|rename|delete>

• list — all tags.
• add --item <id> --name <name> — attaches; creates the tag if the name is new (reuses if it exists).
• remove --item <id> --tag <tag_id> — detach from item.
• rename <tag_id> --name <new>.
• delete <tag_id> — removes the tag everywhere. Confirm intent.

search

matter search "<query>" --type items [--status queue|archive] [--limit n] [--cursor c] [--all]

--type is required (items). Results nest under items: parse .items.results[], not .results[]. Query operators: by:<author>, site:<domain> (e.g. matter search "site:paulgraham.com" --type items).

reading-sessions

matter reading-sessions list — reading history.

Output

Default is JSON — pipe to jq (matter items list --status queue | jq '.results[].title'). Add --plain for human-readable text when showing the user directly. Exit code 0 = success, 1 = error; errors go to stderr. Pagination is cursor-based: loop on has_more + next_cursor, or use --all (mind rate limits).

Full reference

Run matter docs for the complete, always-current CLI + API reference (field schemas, every flag). Prefer it over guessing when you hit an unfamiliar flag — it's ~80 lines and authoritative.

Common pitfalls