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

# Plaud CLI

> Access your Plaud recordings from the terminal — browse, search, read transcripts, download audio, and view AI summaries without opening the app.

## Prerequisites

* Node.js ≥ 20 — [download](https://nodejs.org/)
* A Plaud account

***

## Install

```bash theme={"system"}
npm install -g @plaud-ai/cli
```

***

## Quick start

```bash theme={"system"}
plaud login          # sign in via browser
plaud files          # browse your recordings
plaud search "Q2"    # find a recording by keyword
plaud summary <id>   # read the AI summary
plaud transcript <id> # read the full transcript
```

***

## Command reference

### Authentication

```bash theme={"system"}
plaud login    # sign in via browser — tokens saved automatically
plaud logout   # sign out and revoke authorization
plaud me       # show your current account details
```

### Browse

```bash theme={"system"}
plaud files                   # latest page of recordings
plaud files --page 2 --page-size 50
plaud recent                  # recordings from the last 7 days
plaud recent --days 30        # recordings from the last 30 days
plaud today                   # recordings from today only
```

**`plaud files` options**

| Option            | Description             | Default |
| ----------------- | ----------------------- | ------- |
| `-p, --page`      | Page number (1–1000)    | `1`     |
| `-s, --page-size` | Items per page (10–100) | `20`    |

### Search

```bash theme={"system"}
plaud search <keyword>
plaud search "weekly" --from 2026-04-01 --to 2026-04-30
plaud search "onboarding" --max 10
```

Client-side keyword search (case-insensitive) against recording names. Scans up to 500 most recent recordings.

| Option                | Description                                |
| --------------------- | ------------------------------------------ |
| `--from <YYYY-MM-DD>` | Start of date range (inclusive)            |
| `--to <YYYY-MM-DD>`   | End of date range (inclusive)              |
| `--max <n>`           | Maximum results to display (default: `50`) |

### Read a recording

```bash theme={"system"}
plaud file <id>               # full metadata and availability
plaud audio <id>              # 24-hour download URL for the audio
plaud transcript <id>         # timestamped transcript
plaud transcript <id> -o transcript.txt   # save to file
plaud summary <id>            # AI summary (Markdown)
plaud summary <id> -o summary.md          # save to file
```

### Utility

```bash theme={"system"}
plaud version    # show installed version and build info
plaud update     # check for a newer version and print the upgrade command
```

***

## Data reference

### Fields in `plaud files` / `plaud file`

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| `id`         | Unique recording ID — use this in other commands |
| `name`       | Recording name                                   |
| `created_at` | Creation time (ISO 8601)                         |
| `duration`   | Length of the recording                          |

Additional fields in `plaud file <id>` only:

| Field           | Description                             |
| --------------- | --------------------------------------- |
| `start_at`      | Recording start time (ISO 8601)         |
| `serial_number` | Device serial number                    |
| `audio`         | Whether audio is available for download |
| `transcript`    | Whether a transcript is available       |
| `summary`       | Whether an AI summary is available      |

### Exit codes

| Code | Meaning                                   |
| ---- | ----------------------------------------- |
| `0`  | Success                                   |
| `1`  | Invalid arguments or unknown error        |
| `2`  | Authentication failed — run `plaud login` |
| `3`  | Network error — check your connection     |
| `4`  | Request timed out                         |

All errors are written to **stderr**, keeping stdout clean for piping and scripting:

```
✖ [AUTH_FAILED] Token invalid or expired. Run `plaud login`.
```

***

## Configuration

Tokens are stored at `~/.plaud/tokens.json` and managed automatically — no manual edits needed.

For advanced use, create an optional config file at `~/.plaud/cli.yaml`:

```yaml theme={"system"}
api_base: "https://platform.plaud.ai/developer/api"
timeout: 30000   # milliseconds
```

Environment variables override both the config file and built-in defaults:

| Variable                                  | Purpose                   |
| ----------------------------------------- | ------------------------- |
| `PLAUD_API_BASE`                          | Override the API base URL |
| `PLAUD_CLIENT_ID` / `PLAUD_CLI_CLIENT_ID` | OAuth client ID           |
| `PLAUD_CLIENT_SECRET`                     | OAuth client secret       |
| `PLAUD_AUTH_URL`                          | Authorization endpoint    |
| `PLAUD_TOKEN_URL`                         | Token exchange endpoint   |
| `PLAUD_REFRESH_URL`                       | Token refresh endpoint    |

***

## Upgrade

```bash theme={"system"}
npm install -g @plaud-ai/cli@latest
```

Or check first:

```bash theme={"system"}
plaud update
```

***

## Uninstall

```bash theme={"system"}
npm uninstall -g @plaud-ai/cli
rm -rf ~/.plaud
```

***

## Troubleshooting

| Symptom                                  | Fix                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `401` / "Not authenticated"              | Run `plaud login`                                                                     |
| `plaud: command not found`               | Reopen your terminal; confirm `npm install -g @plaud-ai/cli` completed without errors |
| Token refresh errors                     | Delete `~/.plaud/tokens.json` and run `plaud login` again                             |
| Browser doesn't open during sign-in      | Copy the URL printed in the terminal and open it manually                             |
| `npx` returns `E404` for `@plaud-ai/cli` | Run `npm cache clean --force` and retry                                               |