Kanera CLI

@kanera/cli 將 Kanera 放入終端,以便您可以從 shell 指令碼中查詢卡片、管理工作和自動執行任務。 能夠執行 shell 命令的 AI 編碼代理也可以使用它,無需 MCP 客戶端配置和長時間執行的伺服器。

安裝

需要 Node.js 22 或更高版本。在終端中執行此命令來安裝 kanera 命令全域性:

npm install --global @kanera/cli

已釋出的軟體包沒有執行時依賴項。 確認命令可用:

kanera commands

要嘗試它而不安裝:

npx @kanera/cli commands

認證

透過瀏覽器登入:

kanera auth login

auth login 使用OAuth裝置流,與Claude和Codex的連線方式相同,它會列印一個連結和一個短程式碼,在瀏覽器中開啟連結,並在您批准後自動完成。 選擇"使用"之前,請檢查頁面上的程式碼是否與您的終端匹配 允許訪問。透過 SSH 或在無頭機器上，在任何裝置上開啟連結；透過 --no-browser 跳過一個。

然後,CLI 會儲存一個短期訪問令牌和一個重新整理令牌,並自動對其進行更新。 設定 -> AI 代理 作為 Kanera CLI (您的計算機名稱)，並且它所做的更改會在卡片歷史記錄中標有該名稱。在那裡撤銷它，或者執行 kanera auth logout，這也會在伺服器上結束它。

代理商的名稱

當 AI 代理驅動 CLI 時,請在登入時給它命名,以便其工作被標記為該代理的工作:

kanera auth login --agent "Claude Code"

登入顯示為 Claude 程式碼(在您的計算機名稱上的 Kanera CLI) 在同意螢幕上,在 設定 -> AI 代理，並且作為 透過 Claude 程式碼 (Kanera CLI 上 )... 對於它所做出的每一條評論、卡片更改、通知和代理執行。 KANERA_AGENT_NAME 該名稱在登入期間是固定的,因此給每個代理人分配自己的配置檔案,並且每個配置檔案都包含一個代理人名稱。 --profile 當幾個共享一臺機器時。 --agent 並不適用於 API 金鑰,因為使用私鑰完成的工作將記錄為您。

使用 API 金鑰代替

當沒有人在場來批准瀏覽器登入時,或者當您想要 Kanera 強制執行的憑據為只讀時,可將 API 金鑰用於 CI、cron 作業和無人值守代理。 配置檔案設定 -> API 金鑰，或在 工作區設定 -> API 當憑據應該屬於工作區而不是個人時。 參見 Kanera API 為了區別。

kanera auth login --with-api-key

在託管的 Kanera 上,這將在以下位置開啟您的 API 金鑰頁面: https://board.kanera.app/settings/api-keys，提示輸入金鑰並抑制終端回顯，因此它永遠不會出現在 shell 回滾中，根據 Kanera 驗證它，然後儲存它。

使用個人金鑰所做的更改將被記錄為您，沒有任何影響 透過 您可以透過瀏覽器登入來獲取代理的工作標籤,因此,當您想要標記代理的工作時,瀏覽器登入是更好的選擇。 只讀 當憑據是無人值守代理的時候,CLI 會報告它所持有的作用域,並且拒絕寫入退出,以便代理可以停止而不是重試。

kanera whoami     # who am I, and what may this credential do?
kanera doctor     # diagnose credentials, connectivity, and scope

在 CI 或代理沙盒中,完全跳過儲存的配置檔案並設定 KANERA_API_KEY.

檢查時間線時間表

kanera schedule "$BOARD_ID" --json
kanera schedule --workspaceId "$WORKSPACE_ID" --json
kanera card update MKT-42 --changes.startDateLocalDate 2026-11-02 --changes.dueDateLocalDate 2026-11-06

使用一個作用域:一個板位置引數或 --workspaceId。讀取返回 時間軸 更新更改了引擎的計劃日期、工作日持續時間和間隙、關鍵卡、衝突、預計完成時間以及與最後到期日的偏差。 更新更改了儲存的日期,並且需要寫入許可權;它不會自動移動後續專案。

kanera my-day --json 包括日程表衝突、關鍵工作和錯過的計劃啟動; kanera portfolio --json 事件訂閱需要託管的 HTTP MCP 客戶端;它們不由 CLI 的 stdio 傳輸提供。

日常命令

kanera my-day                    # overdue, due this week, idle, and Up next in one view
kanera work                      # your work across every accessible board
kanera boards                    # every board you can reach, including guest boards
kanera card MKT-42               # a card, by key, id, or URL
kanera card done MKT-42          # mark it complete
kanera comment MKT-42 "Shipped."
kanera search "renewal"
kanera priorities                # an Up next queue
kanera separator create "$BOARD" "$LIST" "This week" --color blue
kanera capture "Renew the venue insurance"   # a task in your private Scratchpad Inbox, no board needed
kanera remind MKT-42 "friday 3pm"            # a private reminder on a card, up to 8 weeks ahead
kanera remind clear MKT-42
kanera reminders                             # your pending reminders, soonest first
kanera watch MKT-42                          # follow a card's activity; kanera unwatch MKT-42 stops
kanera inbox                                 # your latest notifications; then kanera inbox --since "<cursor>" for only what is new
kanera card upload-link MKT-42 test-run.log  # a one-time URL; then curl -fsS -T ./test-run.log "<uploadUrl>"
kanera card attachment MKT-42 "$ATTACHMENT"  # an attachment's text, or an image's details

卡引數接受卡金鑰，例如 MKT-42、卡 ID 或規範卡 URL，這樣您就可以貼上您面前的任何內容。日期引數接受 YYYY-MM-DD 如下短語： "tomorrow 1pm" 或 "next friday"，讀取您個人資料的時區： kanera card update MKT-42 --changes.dueDateLocalDate "friday 3pm".

kanera commands 列出了 CLI 可以做的一切,並且在您登入之前就可以工作。 kanera commands --json 是代理用於發現其餘內容的機器可讀目錄。

完整的刀具表面

上面提到的命令是 Kanera 的 MCP 工具層上的人機工程學快捷方式 — — 人工智慧代理在 MCP 上看到的工具相同。

kanera call cards.bulk_move --boardId "$BOARD" --cardIds[] MKT-42 --cardIds[] MKT-43 --listId "$LIST"
kanera help cards.bulk_move

由於 CLI 直接讀取工具層，而不是重新實現公共 API，因此其命令介面不會偏離代理所看到的內容，並且新新增的工具在釋出之日就可以從 shell 中呼叫。

板隔板

建立一個帶標題的、可選的彩色分隔符,並將其放置在相對於卡片或其他分隔符的位置:

kanera separator create "$BOARD" "$LIST" "This week" --color blue \
  --anchor.side before --anchor.item.type card --anchor.item.id "$CARD"

kanera separator move "$SEPARATOR" "$LIST" \
  --anchor.side after --anchor.item.type separator --anchor.item.id "$OTHER_SEPARATOR"

kanera separator update "$SEPARATOR" --title "Next up" --color green
kanera separator delete "$SEPARATOR"

對於列表邊緣,傳遞 --anchor.side after --anchor.item null 頂部或 --anchor.side before --anchor.item null 分隔符刪除不會改變卡片。 kanera card move 接受相同型別的錨,因此卡片可以放在分隔符之前或之後。

卡牌關係

這些命令從左到右讀:第一張卡片阻擋第二張卡片,兩張卡片必須屬於同一個工作區。

kanera card block MKT-42 WEB-18       # MKT-42 blocks WEB-18
kanera card unblock MKT-42 WEB-18     # remove that dependency
kanera card relate MKT-42 WEB-18      # connect them without a required order
kanera card WEB-18                   # full detail includes relationships
kanera work --filters.blockedOnly true       # find waiting work
kanera work --filters.atRiskOnly true        # blocker overdue or due after the card

對於反向方向或多個目標,請使用底層工具:

kanera call cards.set_relations --cardId WEB-18 --direction blocked_by \
  --otherCardIds[] MKT-42 --otherCardIds[] MKT-43

透過 --remove true 刪除所選關係。 檢查 failed 以及 notAttemptedCardIds 基於部分結果:當另一個目標被拒絕時,成功的加法仍然儲存。 relationsUnavailable 成功寫入名稱 addedCardIds 或 removedCardIds 除了每張卡的拒絕外,還會報告成功刪除的情況。 參見 卡片關係與阻塞 用於許可權、傳遞和完成警告。

依賴圖

使用 kanera deps 用於在一個呼叫中讀取先決條件和下游工作:

kanera deps MKT-42                         # one card's blocking neighbourhood
kanera deps --boardId "$BOARD"             # chains touching a board
kanera deps --workspaceId "$WORKSPACE"      # chains in a workspace

傳遞一個作用域。 card 引數接受其金鑰、UUID 或規範 URL。 focus 直接 blockedBy / blocks IDs, 傳遞式 upstream / downstream 按最近第一序列排列的 ID, relatedTo, 和 onMap。卡片包括可讀的棋盤和列表名稱以及活動/地圖外攔截器計數。結果上限為 400 張卡片和報告 truncated。參見 MCP 圖參考.

論點

標誌對映到工具引數,並使用每個工具自己的 JSON 架構強制執行,而不是透過值的外觀 — 卡鍵可以看起來是數字,ID 可以看起來是布林值。

kanera card update MKT-42 --changes.title "Revised"          # dots nest
kanera work --scope.boardIds[] "$A" --scope.boardIds[] "$B"  # repeat for arrays
kanera call cards.update --json-args '{"cardId":"MKT-42","changes":{"title":"Revised"}}'

陣列引數還接受一個 JSON 陣列，這是傳遞物件列表的最簡單方法。這會在一次呼叫中構建一個清單及其專案和一個子清單，然後在另一個呼叫中完成兩項：

kanera call checklists.create --cardId MKT-42 --title Launch \
  --items '[{"text":"Prepare release","subChecklists":[{"title":"Verification","items":[{"text":"Run smoke tests"}]}]},{"text":"Announce launch"}]'
kanera call checklists.update_items --cardId MKT-42 \
  --updates '[{"itemId":"<itemId>","changes":{"completed":true}},{"itemId":"<itemId>","changes":{"completed":true}}]'

未知標誌,缺少必需引數,形式不正確 --json-args，多餘的位置引數是使用錯誤。 CLI 絕不會默默地丟棄運算元。

輸出

旗幟	輸出
（無）	人類可讀的表格和摘要
--json	一個 { ok, tool, data } 信封
--quiet	裸體結果,管道進入 jq

失敗總是會去 標準錯誤，即使在 --json 重定向 stdout 到檔案時,從不會將錯誤信封混入呼叫者認為是結果資料的內容中。

速率受限和瞬態故障包括 retryable 並且，當 Kanera 供應一個, retryAfter.

出口程式碼

程式碼	意義
0	成功
1	請求失敗
2	Bad usage
3	沒有有效的憑據
4	禁止 — 通常是隻讀憑據,或者論壇上沒有編輯者角色
5	未找到
6	限制率

4 是故意區別於 1。持有讀取範圍金鑰的代理需要告訴“我可能不會這樣做”和“這不起作用”，然後停止而不是重試。

憑據和資料

決議順序： --api-key，那麼 KANERA_API_KEY，然後是儲存的配置檔案，其中包含瀏覽器登入或 API 金鑰。顯式金鑰總是獲勝，因此 CI 作業永遠不會透過開發人員的個人登入執行。

住在 ~/.config/kanera/config.json，用模式寫成 600。命名配置檔案讓一臺機器擁有多個身份：

kanera auth login --profile agent --api-key "kanera_u_live_..."
kanera --profile agent work --json

Command	目 的
kanera auth login	透過瀏覽器登入 (--with-api-key 或 --api-key 找一個關鍵)
kanera auth status	顯示活動憑據及其範圍
kanera auth list	列出儲存的配置檔案
kanera auth token	列印活動 API 金鑰,用於 KANERA_API_KEY=$(kanera auth token)。瀏覽器登入沒有可列印的金鑰。
kanera auth logout	刪除儲存的配置檔案並結束伺服器上的瀏覽器登入

儲存庫可以在不保守秘密的情況下選擇配置檔案， .kanera/config.json:

{ "profile": "agent" }

該檔案不能設定 API 源。 源接收載體憑據,因此檢出的儲存庫不能重定向一個。 --url, KANERA_PUBLIC_API_URL，或在配置檔案中儲存的原點 auth login。非環回源必須使用 HTTPS。

最新情況

CLI 會每天檢查 npm 是否有新版本,當找到時,它會在命令完成後提示:

A new Kanera CLI is available: 1.7.0 → 1.8.0
Update now? [y/N]

回答 y 執行 npm install --global @kanera/cli@<version>。任何其他答案都會跳過更新。 CLI 不會再次詢問一天，並列印命令，以便您稍後更新。

CLI 僅在使用者在互動式終端時詢問,從不檢查或詢問 --json 或 --quiet 當輸入或輸出不是終端時(包括代理、指令碼和管道 ), 當 CI 當你在執行它時, npx，它獲取自己的副本。套裝 KANERA_NO_UPDATE_CHECK=1 關閉該選項。

自我託管 Kanera

瀏覽器登入與您的部署的 MCP 地址繫結，因此在登入期間傳遞它：

kanera auth login --mcp-url https://your-kanera.example/mcp

或設定 KANERA_MCP_URL。 CLI 讀取 MCP 伺服器的 OAuth 後設資料來查詢您的 Kanera 登入頁面，因此無需配置其他任何內容。

對於 API 金鑰,請將 CLI 指向您的公共 API,並將其與配置檔案一起儲存:

kanera auth login --with-api-key --url https://api.your-kanera.example

CLI 無法從其 API 源中判斷自託管 Web 應用的儲存位置,因此,如果使用 API 鍵,則不會開啟瀏覽器。 在 Kanera 下的 Web 應用中建立該鍵 設定 -> API 金鑰，然後根據提示貼上。

或設定 KANERA_PUBLIC_API_URL 每個命令。 kanera doctor 報告解析的端點,這通常是查詢配置錯誤的源的最快方法。

從 AI 代理中使用

兩種方式,它們是互補的。

作為一個外殼工具。 安裝 CLI,為代理提供只讀金鑰,並讓其執行命令。 kanera setup 代理需要的指令:

kanera setup claude    # writes .claude/skills/kanera/SKILL.md
kanera setup codex     # appends Kanera instructions to AGENTS.md
kanera skill           # prints the portable Agent Skill document for any other harness

kanera setup codex 是等效的,所以在升級後重新執行它不會將重複的部分堆疊到您也手動編輯的檔案中。 新增 --global 至 setup claude 為您的帳戶而不是一個專案安裝。

如果代理已連線 Kanera MCP 工具,請使用這些工具而不是 CLI。 在任何傳輸中,只因為 Kanera 也具有 Web 介面,就不應該將支援的卡片讀取和更新歸因於瀏覽器自動化。

作為 MCP 伺服器。 kanera mcp 使用您已儲存的憑據在 stdio MCP 上提供相同的工具:

{
  "mcpServers": {
    "kanera": {
      "command": "kanera",
      "args": ["mcp"]
    }
  }
}

這意味著一個 kanera auth login 您的終端和 MCP 客戶端都覆蓋在一個登入名和密碼中,而不是在另一個位置配置第二個憑據。 kanera mcp 轉發您的 Kanera MCP 當前的伺服器和當前的伺服器之間的連線是什麼? MCP 議定書和以前的修訂，因此任何 MCP 主機可以啟動它。 活動訂閱 由於本地主機沒有託管回撥來傳遞,因此不會透過 stdio 提供。 MCP 與 OAuth 您也可以使用下面的方法: 將 Kanera 連線到您的 AI 代理.

計劃所需資源

瀏覽器登入和個人 API 金鑰適用於每個託管計劃，包括 Free，並且自託管 Kanera 沒有計劃檢查。工作區和主機板 API 鑰匙需要 Pro 或 Pro 若是主辦組織遷移到 Free 他們被撤銷,並且 kanera 使用一個失敗與退出程式碼的命令 3 或 4 直到計劃恢復為止。 API 速率限制 當它在一個組織中被短暫地超越時,CLI 會等待並重試。

相關頁面

• Kanera API
• Kanera TypeScript SDK
• 將 Kanera 連線到您的 AI 代理
• MCP 技術參考