CLI 快速上手
cairn CLI 是 API 的命令列封裝——你（或你的 agent）在終端機操作租戶後台：處理流程、查資訊、產報表，走的是和後台網頁完全相同的業務規則與權限。
本篇帶你從零跑出第一個命令：安裝、登入、認識命令結構，以及對 production 該守的規矩。底層的概念（認證、權限、模組、錯誤格式）見 總覽。
安裝
CLI 隨 repo 一起跑，用 bun run cairn 呼叫：
bun run cairn help
cairn help 列出所有可用資源；cairn <resource> help 列出單一資源的命令。整個 CLI 是自我描述的——不必背命令，問它就好。
目前以 repo 內 bun run cairn … 形式發行。未來會提供 npm 套件 / 獨立執行檔，命令與認證方式不變。
認證
CLI 用 OAuth 2.0 Device Authorization Grant 登入——你從不在終端機輸入密碼。流程是：CLI 取一組驗證碼，你在瀏覽器裡（已登入、含 2FA）核准，CLI 拿到 bearer token。
先設定一個 target（要操作的租戶網域），再登入：
cairn target add demo https://your-tenant.example.com
cairn login
cairn whoami
- 你打哪個租戶的網域，就操作哪個租戶。token 隨租戶網域天然隔離——一個租戶的 token 在別的租戶上自動失效。
- token 帶 2FA：它是「完整登入（含 TOTP）之後」核發的工作階段，CLI 端零認證邏輯。
- token 存在本機（限本人讀寫），每個 target 各自一份；過期會提示你重新
cairn login。 - 登出清除本機 token：
cairn logout。
驗證碼與 token 等同於你的登入。別把它們貼進共用聊天室、log 或腳本明文裡。換機器 / 疑似外洩就 cairn logout 再重新登入。
權限沿用你帳號的角色——CLI 不會給你後台沒有的能力。角色與權限的全貌見 總覽 · 權限與角色，租戶層設定見 設定。
第一個命令
登入後，列出待付款訂單：
cairn orders list --status pending_payment
加 --json 得到機器可讀輸出，方便管線 / agent 解析：
cairn orders list --status pending_payment --json
cairn orders get <id> --json
cairn whoami --json
不加 --json 時，輸出是給人看的精簡表格；加了就回 API 的原始 JSON。
命令結構
絕大多數命令都是同一個形狀：
cairn <resource> <verb> [positional] [--flags]
| 部位 | 是什麼 | 例 |
|---|---|---|
<resource> | 操作的資源（共 32 種） | orders、trips、members、reports |
<verb> | 動作 | list、get、mark-paid、monthly |
| positional | 主鍵（通常是 id） | cairn orders get <id> |
--flags | 篩選 / 欄位 / 選項 | --status、--year、--json |
幾個全域旗標在所有命令通用：
| 旗標 | 作用 |
|---|---|
--target <name> | 指定要操作的 target（預設為目前 target） |
--json | 機器可讀輸出 |
--confirm | 對 production target 寫入時必帶（見下） |
多個 target 之間切換：
cairn target list
cairn target use demo
cairn orders list --target staging # 單次覆寫，不切換目前 target
CLI ↔ API 對應
CLI 不是另一條捷徑——它是 /api/v1 的薄封裝。每個命令都對應一個端點，走相同的權限檢查與稽核：
| CLI 命令 | 對應端點 |
|---|---|
cairn orders list | GET /api/v1/orders |
cairn orders get <id> | GET /api/v1/orders/{id} |
cairn orders mark-paid <id> | POST /api/v1/orders/{id}/mark-paid |
cairn reports monthly --year 2026 --month 6 | GET /api/v1/reports/monthly |
cairn members get <userId> | GET /api/v1/members/{userId} |
CLI 參考 每個命令都標了它對應的端點；API 參考 每個端點都標了它要求的權限。兩份文件互為索引——用 CLI 還是直接打 API 隨你，行為一致。
Production 安全
把正式環境的 target 標成 production，CLI 就會在任何寫入命令上要求 --confirm，避免手滑打到正式資料：
cairn target add prod https://your-tenant.example.com --production
cairn orders mark-paid <id> # ✗ 被擋下：production target 需 --confirm
cairn orders mark-paid <id> --confirm # ✓ 明確確認後才送出
--confirm 只是 client 端的減速丘，不是授權。真正的守衛永遠在 server：每個寫入端點都會重跑 requirePermission，權限不足一律回 403 forbidden，與你有沒有加 --confirm 無關。
讀取命令（list / get / 報表）不需要 --confirm。owner-scope 一律由 server 依你的 token 重算——例如業務經 CLI 也只看得到自己經手的訂單，和後台完全等價。