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

> 從終端機存取您的 Plaud 錄音 — 無需打開應用程式，就能瀏覽、搜尋、閱讀逐字稿、下載音訊檔，並查看 AI 摘要。

## 先決條件

* Node.js ≥ 20 — [下載](https://nodejs.org/)
* Plaud 帳戶

***

## 安裝

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

***

## 快速開始

```bash theme={"system"}
plaud login          # 透過瀏覽器登入
plaud files          # 瀏覽您的錄音
plaud search "Q2"    # 透過關鍵字搜尋錄音
plaud summary <id>   # 閱讀 AI 摘要
plaud transcript <id> # 閱讀完整逐字稿
```

***

## 命令參考

### 驗證

```bash theme={"system"}
plaud login    # 透過瀏覽器登入 — 自動儲存權杖
plaud logout   # 登出並撤銷授權
plaud me       # 顯示您目前的帳戶詳細資訊
```

### 瀏覽

```bash theme={"system"}
plaud files                   # 最新的錄音頁面
plaud files --page 2 --page-size 50
plaud recent                  # 最近 7 天的錄音
plaud recent --days 30        # 最近 30 天的錄音
plaud today                   # 僅今天的錄音
```

**`plaud files`選項**

| 選項                | 說明            | 預設   |
| ----------------- | ------------- | ---- |
| `-p, --page`      | 頁碼 (1–1000)   | `1`  |
| `-s, --page-size` | 每頁項目數（10–100） | `20` |

### 搜尋

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

在用戶端針對錄音名稱進行關鍵字搜尋（不區分大小寫）。最多掃描 500 則最新錄音。

| 選項                    | 說明               |
| --------------------- | ---------------- |
| `--from <YYYY-MM-DD>` | 起始日期（包含）         |
| `--to <YYYY-MM-DD>`   | 結束日期（包含）         |
| `--max <n>`           | 最多顯示結果數（預設：`50`） |

### 閱讀錄音逐字稿

```bash theme={"system"}
plaud file <id>               # 完整的中繼資料和可用性
plaud audio <id>              # 有效期限 24 小時的音訊檔下載連結
plaud transcript <id>         # 附帶時間戳記的逐字稿
plaud transcript <id> -o transcript.txt   # 儲存到檔案
plaud summary <id>            # AI 摘要（Markdown）
plaud summary <id> -o summary.md          # 儲存到檔案
```

### 工具

```bash theme={"system"}
plaud version    # 顯示已安裝的版本和組建資訊
plaud update     # 檢查是否有更新版本並列印升級指令
```

***

## 資料參照

### `plaud files` / `plaud file` 中的欄位

| 欄位           | 說明                     |
| ------------ | ---------------------- |
| `id`         | 唯一錄音 ID — 在其他命令中使用此 ID |
| `name`       | 錄音名稱                   |
| `created_at` | 建立時間 (ISO 8601)        |
| `duration`   | 錄音長度                   |

僅限 `plaud file <id>` 的附加欄位：

| 欄位              | 說明                |
| --------------- | ----------------- |
| `start_at`      | 錄音開始時間 (ISO 8601) |
| `serial_number` | 裝置序號              |
| `audio`         | 是否有音訊可供下載         |
| `transcript`    | 是否有逐字稿可用          |
| `summary`       | 是否有 AI 摘要可用       |

### 退出代碼

| 代碼  | 意義                      |
| --- | ----------------------- |
| `0` | 成功                      |
| `1` | 引數無效或發生未知錯誤             |
| `2` | 驗證失敗 — 執行 `plaud login` |
| `3` | 網路錯誤 — 請檢查您的連線          |
| `4` | 請求超時                    |

所有錯誤都寫入 **stderr**，以保持 stdout 乾淨，便於管線傳輸和指令碼處理：

```
✖ [AUTH_FAILED] 權杖無效或已過期。執行 `plaud login`。
```

***

## 組態設定

權杖儲存在 `~/.plaud/tokens.json` 並自動管理 — 無需手動編輯。

對於進階使用，請在 `~/.plaud/cli.yaml` 建立一個可選的組態檔：

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

環境變數會覆寫組態檔和內建預設值：

| 變數                                        | 目的            |
| ----------------------------------------- | ------------- |
| `PLAUD_API_BASE`                          | 覆寫 API 基礎 URL |
| `PLAUD_CLIENT_ID` / `PLAUD_CLI_CLIENT_ID` | OAuth 用戶端 ID  |
| `PLAUD_CLIENT_SECRET`                     | OAuth 用戶端密鑰   |
| `PLAUD_AUTH_URL`                          | 授權端點          |
| `PLAUD_TOKEN_URL`                         | 權杖交換端點        |
| `PLAUD_REFRESH_URL`                       | 權杖重新整理端點      |

***

## 升級

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

或先檢查：

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

***

## 解除安裝

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

***

## 疑難排解

| 症狀                                | 修正                                                |
| --------------------------------- | ------------------------------------------------- |
| `401` / "未經驗證"                    | 執行 `plaud login`                                  |
| `plaud:command not found`         | 重新打開終端機；確認 `npm install -g @plaud-ai/cli` 完成且沒有錯誤 |
| 權杖重新整理錯誤                          | 刪除 `~/.plaud/tokens.json` 並再次執行 `plaud login`     |
| 瀏覽器在登入期間無法開啟                      | 複製終端機中列印的 URL 並手動打開                               |
| `npx` 回傳 `E404` 於 `@plaud-ai/cli` | 執行 `npm cache clean --force` 並重試                  |