Quickstart

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

macOS / Linux
Windows
From source

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

irm https://cli.getmatter.com/install.ps1 | iex

git clone https://github.com/getmatterapp/matter-cli.git
cd matter-cli
bun install
bun run src/cli.tsx --help

Authenticate

# Opens browser to copy your API token
matter login

# Or pass a token directly
matter login mat_yourtoken

# Piped input (for automation)
echo "$MATTER_TOKEN" | matter login

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

The CLI updates itself automatically. New releases are downloaded in the background and applied on the next run. To update immediately:

matter update

Getting Started

Install

Authenticate

Quick examples

Output formats

Updating

Next steps

Commands

Interactive TUI

​Install

​Authenticate

​Quick examples

​Output formats

​Pagination

​Updating

​Next steps

Commands

Interactive TUI

Install

Authenticate

Quick examples

Output formats

Pagination

Updating

Next steps