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 技术参考