> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install and use the Matter CLI to manage your reading library from the terminal.

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

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://cli.getmatter.com/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://cli.getmatter.com/install.ps1 | iex
    ```
  </Tab>

  <Tab title="From source">
    ```bash theme={null}
    git clone https://github.com/getmatterapp/matter-cli.git
    cd matter-cli
    bun install
    bun run src/cli.tsx --help
    ```
  </Tab>
</Tabs>

## Authenticate

Log in with your Matter API token:

```bash theme={null}
# 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](/api/authentication) for how to generate a token.

## Quick examples

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```bash theme={null}
matter update
```

## Next steps

<CardGroup cols={2}>
  <Card title="Commands" icon="rectangle-terminal" href="/cli/commands">
    Full reference for every CLI command.
  </Card>

  <Card title="Interactive TUI" icon="tv" href="/cli/tui">
    Browse your library visually in the terminal.
  </Card>
</CardGroup>