@harukibox/cli

@harukibox/cli

官方 harukibox 命令列工具。純粹是 Agent API 的薄薄一層 wrapper，不會自己呼叫任何 AI。

安裝

npm install -g @harukibox/cli

登入

最簡單的方式（OAuth 2.1 PKCE，瀏覽器自動跳）：

harukibox login

CLI 會：

• 起一個 localhost server，產生 PKCE verifier/challenge
• 開你的預設瀏覽器到 harukibox 的 /oauth/authorize
• 你在網頁登入後按「授權」，瀏覽器自動 callback 回 localhost
• CLI 用 code + verifier 換到 token，存到 ~/.config/harukibox/config.json（mode 0600）

沒有桌面瀏覽器（SSH、devcontainer、CI）？

CLI 會自動退回 RFC 8628 device flow：

🔐 在瀏覽器開啟下方網址並輸入代碼：
   https://harukibox.com/oauth/device
   代碼：BHJK-MNPQ

你開任何一台有瀏覽器的裝置，到該網址輸入代碼即可。

也可以強制走 device flow：

harukibox login --device

Power user / 自動化腳本

如果已經有 hrk_live_* token（例如從另一台機器跑過 harukibox login），可手動帶入：

harukibox login --token hrk_live_xxx
# 或用環境變數
HARUKIBOX_TOKEN=hrk_live_xxx harukibox whoami

常用指令

harukibox whoami
harukibox products list --search 'pokemon' --limit 50
harukibox products get <product-id>
harukibox products create --name "新商品" --sku "ABC-001" --price-twd 1500
harukibox orders list --status pending
harukibox buyers list --search "陳"
harukibox shipments list
harukibox search "海賊王"
harukibox logout                # 預設 RFC 7009 撤銷伺服器 token + 刪本地 config
harukibox logout --keep-remote  # 只刪本地 config（token 仍在伺服器有效到期）

--json 旗標把輸出改成原始 JSON，方便 pipe 給 jq：

harukibox products list --limit 5 --json | jq '.data[].name'

MCP 指令

CLI 內建一個符合 MCP 2026-07-28 的 client，直接對 remote MCP endpoint （/api/agent/mcp）講 Streamable HTTP —— 不必開 Claude Desktop 就能操作與除錯。

harukibox mcp discover                      # server/discover：支援版本 / capabilities / instructions
harukibox mcp tools                         # tools/list
harukibox mcp call haruki_me                # tools/call
harukibox mcp call haruki_search --q "海賊王"
harukibox mcp call haruki_list_products --args '{"limit":5,"status":"預購"}'
harukibox mcp check                         # 合規檢查

mcp call 兩種傳參數的方式：--args '<json>' 給整包 JSON，或直接用 --key value（自動轉 camelCase，純數字轉 number）。

harukibox mcp check

對 endpoint 逐條驗證 2026-07-28 的 MUST，任何一條沒過就 exit 1：

✅ server/discover implemented
✅ advertises supportedVersions — 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26
✅ result carries resultType: 'complete'
✅ tools/list is cacheable — ttlMs=3600000 cacheScope=public
✅ unsupported version → 400 + -32022
✅ Mcp-Method mismatch → 400 + -32020
✅ unknown method → 404 + -32601
✅ GET → 405
✅ legacy initialize still answered — protocolVersion=2025-06-18

自架站也能測：harukibox mcp check --base-url https://your-instance.example.com/api/agent

Self-host / 私有部署

harukibox login --token hrk_live_xxx --base-url https://your-instance.example.com/api/agent

安全

• Token 一律以 Bearer header 傳送，走 HTTPS
• Config 檔 mode 0600，僅當前 user 可讀
• 過期 / 撤銷 / IP 不在 allowlist 時呼叫會立即被拒，CLI 顯示伺服器回的錯誤訊息
• 每次呼叫都會被記錄到伺服器端 audit log（沒有 web UI 查詢；如需匯出請與服務方聯繫）

License

MIT