Skip to main content
The Matter CLI lets you manage your library from the terminal. It works in two modes: CLI mode for scripting and automation (JSON output by default), and an interactive TUI for browsing your library visually.

​
Install

curl -fsSL https://cli.getmatter.com/install.sh | sh

​
Authenticate

Log in with your Matter API token: 
# Opens browser to copy your API token
matter login

# Or paste a token directly
matter login-with-token

# Piped input (for automation)
echo "$MATTER_TOKEN" | matter login-with-token
Your token is stored at ~/.config/matter/config.json. See Authentication for how to generate a token.

​
Quick examples

# Check your account
matter account --plain

# List your queue
matter items list --status queue --plain

# Save a URL
matter items save --url "https://paulgraham.com/greatwork.html"

# Get a specific item with full details
matter items get itm_r9f3a

# List annotations on an item
matter annotations list --item itm_r9f3a

# Tag an item
matter tags add --item itm_r9f3a --name "essays"

# Archive an item
matter items update itm_r9f3a --status archive

​
Output formats

JSON (default) — structured output for scripting and piping: 
{
  "object": "list",
  "results": [...],
  "has_more": true,
  "next_cursor": "cur_abc123"
}
Plain text (--plain) — human-readable table output: 
itm_r9f3a  How to Do Great Work          paulgraham.com  queue     35%
itm_k8w2p  The Art of Finishing           example.com     archive  100%
Errors go to stderr. Exit code 0 for success, 1 for errors.

​
Pagination

List commands support cursor-based pagination: 
# First page
matter items list --limit 10

# Next page (use next_cursor from previous response)
matter items list --limit 10 --cursor <cursor>

# Fetch all pages at once
matter items list --all

​
Updating

matter update
matter version

​
Next steps

Commands

Full reference for every CLI command.

Interactive TUI

Browse your library visually in the terminal.