> ## 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.

# Commands

> Full reference for every Matter CLI command.

All commands output JSON by default. Add `--plain` for human-readable output.

## Account

```bash theme={null}
matter account              # JSON
matter account --plain      # Human-readable
```

Returns your account info including name, email, and Pro status.

## Items

### List items

```bash theme={null}
matter items list [options]
```

| Option            | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `--status`        | Filter by status: `inbox`, `queue`, `archive`, `all`                                                          |
| `--content-type`  | Filter by type: `article`, `podcast`, `video`, `pdf`, `tweet`, `email`                                        |
| `--favorite`      | Only favorited items                                                                                          |
| `--tag`           | Filter by tag ID                                                                                              |
| `--order`         | Sort order: `updated`, `library_position`, `inbox_position` (position orderings use app ordering, nulls last) |
| `--updated-since` | Filter by updated date (ISO 8601)                                                                             |
| `--limit`         | Results per page (default 25, max 100)                                                                        |
| `--cursor`        | Pagination cursor from previous response                                                                      |
| `--all`           | Fetch all pages                                                                                               |
| `--plain`         | Human-readable output                                                                                         |

```bash theme={null}
matter items list --status queue --plain
matter items list --content-type article --favorite --limit 10
matter items list --status archive --all
```

### Get an item

```bash theme={null}
matter items get <id>
matter items get itm_r9f3a --plain
```

### Save a URL

```bash theme={null}
matter items save --url <url> [--status queue|archive]
```

```bash theme={null}
matter items save --url "https://example.com/article"
matter items save --url "https://example.com/article" --status queue
```

### Update an item

```bash theme={null}
matter items update <id> [options]
```

| Option       | Description                       |
| ------------ | --------------------------------- |
| `--status`   | Move to `queue` or `archive`      |
| `--favorite` | Set favorite (`true` or `false`)  |
| `--progress` | Reading progress (`0.0` to `1.0`) |

```bash theme={null}
matter items update itm_r9f3a --status archive
matter items update itm_r9f3a --favorite true
```

### Delete an item

```bash theme={null}
matter items delete <id>
```

## Search

```bash theme={null}
matter search <query> --type <type> [options]
```

Full-text search across Matter, ranked by relevance. Results are grouped by type.

| Option     | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `--type`   | **(required)** Result types, comma-separated (e.g. `items`)            |
| `--status` | Filter items by status: `queue`, `archive`. Omit to search all content |
| `--limit`  | Results per page (default 25, max 100)                                 |
| `--cursor` | Pagination cursor from previous response                               |
| `--all`    | Fetch all pages                                                        |
| `--plain`  | Human-readable output                                                  |

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

| Operator      | Description                | Example            |
| ------------- | -------------------------- | ------------------ |
| `"phrase"`    | Exact phrase match         | `"deep learning"`  |
| `-term`       | Exclude term               | `-podcast`         |
| `by:name`     | Filter by author/publisher | `by:graham`        |
| `site:domain` | Filter by domain           | `site:nytimes.com` |
| `title:word`  | Match in title only        | `title:review`     |

## Annotations

### List annotations

```bash theme={null}
matter annotations list --item <item_id> [options]
```

| Option     | Description                              |
| ---------- | ---------------------------------------- |
| `--item`   | **(required)** Item ID                   |
| `--limit`  | Results per page (default 25, max 100)   |
| `--cursor` | Pagination cursor from previous response |
| `--all`    | Fetch all pages                          |
| `--plain`  | Human-readable output                    |

```bash theme={null}
matter annotations list --item itm_r9f3a --plain
matter annotations list --item itm_r9f3a --all
```

### Get an annotation

```bash theme={null}
matter annotations get <id>
matter annotations get ann_k3m9p
```

### Update an annotation

```bash theme={null}
matter annotations update <id> --note "Updated note"
```

### Delete an annotation

```bash theme={null}
matter annotations delete <id>
```

## Tags

### List all tags

```bash theme={null}
matter tags list
matter tags list --plain
```

### Rename a tag

```bash theme={null}
matter tags rename <id> --name "new name"
```

### Delete a tag

```bash theme={null}
matter tags delete <id>
```

### Add a tag to an item

```bash theme={null}
matter tags add --item <item_id> --name "tag name"
```

Creates the tag if it doesn't exist.

### Remove a tag from an item

```bash theme={null}
matter tags remove --item <item_id> --tag <tag_id>
```

## Auth

### Log in

```bash theme={null}
matter login                # Opens browser to get token
matter login <token>        # Pass token directly
```

### Interactive TUI

```bash theme={null}
matter tui                  # Launch the interactive terminal UI
```

Also launches when you run `matter` with no arguments. See [Interactive TUI](/cli/tui) for keyboard shortcuts.

### Self-update

The CLI auto-updates in the background. New releases are downloaded while your command runs and applied on the next invocation. To update immediately instead:

```bash theme={null}
matter update               # Update now (instead of waiting for next run)
matter version              # Show current version
```

## Readonly mode

Enable readonly mode to prevent write operations (save, update, delete):

```bash theme={null}
# Toggle in TUI settings, or edit ~/.config/matter/config.json
```

When enabled, all write commands will be rejected with an error.