Skip to main content
All commands output JSON by default. Add --plain for human-readable output.

​
Account

matter account              # JSON
matter account --plain      # Human-readable
Returns your account info including name, email, and Pro status.

​
Items

​
List items

matter items list [options]
OptionDescription
--statusFilter by status: inbox, queue, archive, all
--content-typeFilter by type: article, podcast, video, pdf, tweet, email
--favoriteOnly favorited items
--tagFilter by tag ID
--orderSort order: updated, library_position, inbox_position (position orderings use app ordering, nulls last)
--updated-sinceFilter by updated date (ISO 8601)
--limitResults per page (default 25, max 100)
--cursorPagination cursor from previous response
--allFetch all pages
--plainHuman-readable output
matter items list --status queue --plain
matter items list --content-type article --favorite --limit 10
matter items list --status archive --all

​
Get an item

matter items get <id>
matter items get itm_r9f3a --plain

​
Save a URL

matter items save --url <url> [--status queue|archive]

matter items save --url "https://example.com/article"
matter items save --url "https://example.com/article" --status queue

​
Update an item

matter items update <id> [options]
OptionDescription
--statusMove to queue or archive
--favoriteSet favorite (true or false)
--progressReading progress (0.0 to 1.0)
matter items update itm_r9f3a --status archive
matter items update itm_r9f3a --favorite true

​
Delete an item

matter items delete <id>

matter search <query> --type <type> [options]
Full-text search across Matter, ranked by relevance. Results are grouped by type.
OptionDescription
--type(required) Result types, comma-separated (e.g. items)
--statusFilter items by status: queue, archive. Omit to search all content
--limitResults per page (default 25, max 100)
--cursorPagination cursor from previous response
--allFetch all pages
--plainHuman-readable output
matter search "machine learning" --type items --plain
matter search "by:graham" --type items --status queue
matter search "\"deep work\"" --type items --all
matter search "site:nytimes climate" --type items --limit 10

​
Search operators

OperatorDescriptionExample
"phrase"Exact phrase match"deep learning"
-termExclude term-podcast
by:nameFilter by author/publisherby:graham
site:domainFilter by domainsite:nytimes.com
title:wordMatch in title onlytitle:review

​
Annotations

​
List annotations

matter annotations list --item <item_id> [options]
OptionDescription
--item(required) Item ID
--limitResults per page (default 25, max 100)
--cursorPagination cursor from previous response
--allFetch all pages
--plainHuman-readable output
matter annotations list --item itm_r9f3a --plain
matter annotations list --item itm_r9f3a --all

​
Get an annotation

matter annotations get <id>
matter annotations get ann_k3m9p

​
Update an annotation

matter annotations update <id> --note "Updated note"

​
Delete an annotation

matter annotations delete <id>

​
Tags

​
List all tags

matter tags list
matter tags list --plain

​
Rename a tag

matter tags rename <id> --name "new name"

​
Delete a tag

matter tags delete <id>

​
Add a tag to an item

matter tags add --item <item_id> --name "tag name"
Creates the tag if it doesn’t exist.

​
Remove a tag from an item

matter tags remove --item <item_id> --tag <tag_id>

​
Auth

​
Log in

matter login                # Opens browser
matter login-with-token     # Paste token

​
Self-update

matter update               # Update to latest version
matter version              # Show current version

​
Readonly mode

Enable readonly mode to prevent write operations (save, update, delete): 
# Toggle in TUI settings, or edit ~/.config/matter/config.json
When enabled, all write commands will be rejected with an error.