Paddi — AI Product Management Agent

在終端機中使用 Paddi 的完整指令參考：安裝、身份驗證、設定與所有指令。

Paddi CLI（指令 paddi）讓你在終端機中完成 Paddi 的完整工作流程：把原始回饋灌入 Paddi（capture）、檢視依 RIGE 分數排序並附有 solution paths 的需求（request）、回答 solution paths 以產生規格文件（spec），以及管理已串接的資料來源（source）。

安裝

Homebrew（macOS / Linux）

brew install paddi-app/tap/paddi

pip / uv

pip install paddi-cli
# 或
uv tool install paddi-cli

Node.js

Scoop（Windows）

scoop bucket add paddi-app https://github.com/paddi-app/scoop-bucket
scoop install paddi

Winget（Windows）

winget install Paddi.Paddi

Go

go install github.com/paddi-app/paddi@latest

快速開始

paddi auth login
paddi workspace switch
paddi project switch

全域旗標

以下旗標可套用在任何子指令之前：

旗標	說明
`--json`	輸出 API 回傳的原始 JSON，取代預設的表格／文字格式
`--quiet`, `-q`	只輸出必要結果（例如條列指令只印出 ID），適合腳本串接
`--project <id>`	覆寫目前的專案情境，優先於設定檔與 `PADDI_PROJECT`
`--api-base <url>`	覆寫 API 位址，優先於 `PADDI_API_BASE` 與設定檔
`--version`, `-V`	印出版本號
`--help`, `-h`	顯示說明（任何指令或子指令皆可加上）

輸出格式

預設：條列指令輸出對齊的表格；單一資源指令（如 spec view、request view）輸出可讀的文字說明。
--json：輸出後端回傳的原始 JSON，方便搭配 jq 等工具處理。多數指令直接透傳 API 回應；例外是 spec info，其 JSON 是用戶端重新序列化的中繼資料（欄位對應 Spec 結構，content 欄位固定為空字串）。
--quiet：條列指令只印出每列的 ID；建立／變更類指令（如 capture create、spec download）省略確認訊息，只印出關鍵值（ID 或檔案路徑）。

設定與環境變數

設定採以下優先順序：旗標 > 環境變數 > 設定檔 > 預設值。

設定檔

預設位置為 $XDG_CONFIG_HOME/paddi/config.toml；若未設定 XDG_CONFIG_HOME，則為 <使用者家目錄>/.config/paddi/config.toml（各平台皆同，包含 Windows）。可用 PADDI_CONFIG 環境變數完全覆寫路徑。

paddi workspace switch / paddi project switch 會寫入此檔案；一般不需手動編輯，內容格式如下：

api_base = "https://api.paddi.app"

[context]
workspace_id = "ws_123"
project_id = "proj_456"

環境變數

變數	說明
`PADDI_TOKEN`	直接指定存取權杖，取代 OS 憑證儲存區並停用自動 token 更新。適合 CI／非互動環境
`PADDI_CONFIG`	覆寫設定檔路徑
`PADDI_API_BASE`	覆寫 API 位址
`PADDI_PROJECT`	覆寫目前的專案情境

context.workspace_id 沒有對應的旗標或環境變數，僅能透過 paddi workspace switch 設定，或在 paddi project switch 選擇了不同工作區底下的專案時自動一併更新。

身份驗證

paddi auth login
paddi auth status
paddi auth logout

login：採 device flow：印出一次性代碼與驗證網址；若目前終端機為互動式（TTY），按下 Enter 會自動開啟瀏覽器，否則需自行開啟網址並輸入代碼。之後會依後端指定的間隔輪詢（預設 5 秒），最長等待 15 分鐘，逾時或代碼過期則登入失敗。
status：顯示目前登入的使用者、目前的工作區與專案。
logout：撤銷伺服器端的 session，並清除本機憑證與設定檔（工作區／專案情境也會一併清除）。

登入後的存取權杖與更新權杖會存放於作業系統的憑證儲存區（macOS Keychain、Windows Credential Manager、Linux Secret Service），不會明文寫入設定檔。存取權杖過期時會自動以更新權杖換發；若透過 PADDI_TOKEN 提供權杖，則略過憑證儲存區與自動更新，需自行確保該權杖有效。

Logged in as Jane Doe (jane@example.com)
Workspace: Acme Inc
Project:   Landing Page Revamp

ID       NAME       ROLE    PROJECTS
ws_123   Acme Inc   Admin   4

`paddi workspace switch [workspace-id]`

設定目前的工作區。省略 workspace-id 時會列出所有工作區，以 ↑/↓（或 j/k）選擇、Enter 確認、q 取消。

paddi workspace switch ws_123

`paddi project`

管理專案情境，多數其他指令都需要先選定專案。

`paddi project list`

列出目前工作區底下的專案。

ID          NAME                DESCRIPTION
proj_456    Landing Page Revamp 針對行銷網站首頁的重新設計

`paddi project switch [project-id]`

設定目前的專案；若指定的專案屬於不同工作區，會一併切換目前的工作區。省略 project-id 時會出現互動式選單（操作方式同 workspace switch）。

paddi project switch proj_456

`paddi capture`

將原始回饋灌入目前的專案。

`paddi capture list`

列出目前專案的 capture。

ID        NAME                  STATUS     CREATED
cap_789   匯出功能找不到入口    pending    2026-07-19 09:00

`paddi capture create`

旗標	說明
`--message`, `-m <text>`	直接以文字提供回饋內容
`--file`, `-f <path>`	從檔案讀取回饋內容；傳入 `-` 表示改讀 stdin

必須擇一提供內容來源：-m、-f <path>、-f -，或直接帶一個 - 位置參數（同樣代表讀 stdin）。

paddi capture create -m "客戶反應匯出功能找不到入口"
echo "來自 Slack 的回饋內容" | paddi capture create -

Capture cap_789 created.

`paddi request`

檢視與推進由 capture 分析而成的需求（request）。

`paddi request list`

列出目前專案的需求，依 RIGE 分數（Reach × Impact × Goal Alignment ÷ Effort）由高到低排序。

ID        NAME                  TYPE     STATUS   SCORE
req_001   匯出功能難以發現      feature  scored   8.4

`paddi request view <request-id>`

顯示需求的完整內容：RIGE 各項分數、描述、分析、關聯的 capture 數量、solution paths（含選項與目前的選擇），以及已產生的 spec（若存在）。

匯出功能難以發現 (req_001)
Type: feature  Status: scored  Score: 8.4
RIGE: reach 0.8 x impact 0.9 x goal 0.75 / effort 0.3

Description:
...

Solution paths:
1. 是否需要保留舊的匯出入口？ (sp_01)
   Context: ...
   - 保留並新增捷徑 — 風險低，開發量小
   - 完全移除舊入口 — 需要額外的遷移引導
   > selected: 保留並新增捷徑

`paddi request regenerate <request-id>`

旗標	說明
`--expectation`, `-e <text>`	給予重新產生 solution paths 時的期望方向（選填）

paddi request regenerate req_001 -e "偏好低風險、可漸進上線的方案"

`paddi request draft <request-id>`

旗標	說明
`--file`, `-f <path>`	必填。回答內容的 JSON 檔案，傳入 `-` 表示改讀 stdin

回答送出後會觸發 spec 產生。JSON 內容可以是純陣列，或包在 {"answers": [...]} 之中；每筆回答對應一個 solution path：

[
  {
    "solution_path_id": "sp_01",
    "selections": [{ "label": "保留並新增捷徑", "custom": false }]
  }
]

selections[].custom 標示這個選擇是否為使用者自行輸入的自訂答案（而非既有選項）。

paddi request draft req_001 -f answers.json

`paddi spec`

管理由需求產生的規格文件。

`paddi spec list`

列出目前專案的 spec，依建立時間新到舊排序。

ID         TITLE                REQUEST TYPE  LOCKED  CREATED
spec_111   匯出入口重新設計      feature       no      2026-07-18

`paddi spec info <spec-id>`

印出 spec 的中繼資料（標題、ID、所屬 request ID、鎖定狀態、建立時間），不含 markdown 內容。

匯出入口重新設計 (spec_111)
Request ID: req_001
Locked: no
Created: 2026-07-18 10:32

`paddi spec view <spec-id>`

印出 spec 的完整 markdown 內容（含標題）。

paddi spec view spec_111

`paddi spec download <spec-id>`

旗標	說明
`--output`, `-o <path>`	輸出檔案路徑；預設為 `<標題>.md`（標題中的路徑分隔符號等字元會替換為 `-`）

paddi spec download spec_111 -o docs/export-redesign.md

`paddi spec lock <spec-id>`

鎖定 spec，之後不可再編輯。

paddi spec lock spec_111

`paddi source`

管理已串接的資料來源。

`paddi source list`

列出目前專案的資料來源。

ID        PROVIDER   TYPE     NAME              STATUS  LAST INDEXED
src_222   slack      channel  #customer-voice   ok      2026-07-19 09:00

`paddi source index <source-id>`

觸發該資料來源重新索引。

paddi source index src_222

離開代碼

腳本可依離開代碼判斷失敗原因：

代碼	意義
`0`	成功
`1`	使用者錯誤（參數錯誤、未選定專案等）
`2`	身份驗證錯誤（尚未登入，或 API 回傳 401 / 403）
`3`	伺服器或網路錯誤（API 回傳 5xx，或連線失敗）

CLI

On this page