使用 CLI · Comu OpenAPI

Use cases

在哪些场景用

把你今天用 curl 干的所有事都更短地干掉，下面是 4 个最典型的场景。

日常脚本里调业务接口

不用记 base URL、不用拼 Bearer、不用每次写 jq。 kirby api POST /xxx --body @data.json 就够了；错误码自动映射到退出码，脚本里 if 一下就分支。

Agent / LLM 工具调用

kirby spec list 让 Agent 看到有哪些能力； kirby api 把 Agent 的决定落到真实请求上。非 TTY 自动 JSON，Agent 直接消费 stdout。

CI / 流水线自检

在 build 步骤前加一行 kirby doctor 检查网络与凭据，再用 kirby spec list 验收新版本接口是否齐全。

多环境一键切换

--profile prod / --profile staging 切凭据，不用改 ~/.bashrc、不用 source env 文件、不用切容器。

CLI modules

四个业务模块

FAQ、actionList、笔记、联系人四个模块，覆盖 40 个开放查询接口。笔记导出在本地组合查询结果。

业务命令需要先登录，仅提供查询能力。新增查询返回完整 JSON，脚本统一使用 --output json。FAQ 的 --language 默认 en-US。

FAQ5 个命令

权限：有效 Bearer Token，无额外 scope

命令	选项	用途
`kirby faq categories`	`--language`	查询 FAQ 分类
`kirby faq category <category_key>`	`--language`	查询分类详情
`kirby faq get <faq_id>`	`--language`	按 ID 查询 FAQ
`kirby faq question <question_code>`	`--language`	按问题代码查询 FAQ
`kirby faq search`	`--keyword` / `--category-id` / `--device-id` / `--language`	搜索 FAQ

bash

kirby faq search --language zh-CN --keyword "录音"

actionList4 个命令

权限：action_items:read

别名：action-list / actions

命令	选项	用途
`kirby actionList list`	`--page` / `--page-size` / `--keyword` / `--order`	分页查询行动清单
`kirby actionList get <action_id>`	—	查询行动项详情
`kirby actionList by-note <note_id>`	—	查询笔记关联行动项
`kirby actionList recent`	`--limit`	查询最近行动清单

bash

kirby actionList list --page 1 --page-size 20

笔记管理20 个命令

权限：note:read

命令	选项	用途
`kirby note list`	`--page` / `--page-size` / `--trash` / `--dir-id` / `--note-id` / `--trans-success` / `--summary-success` / `--feature-audio-success` / `--temp-audio-url`	分页列出笔记
`kirby note get <note_id>`	—	获取笔记详情
`kirby note search`	`--keywords` * / `--page` / `--page-size`	搜索笔记
`kirby note summary <note_id>`	—	获取笔记摘要
`kirby note trans <note_id>`	—	获取笔记转录文本
`kirby note export <note_id>`	`--format`	导出笔记（摘要+转录）
`kirby note audio-url <note_id>`	—	查询音频临时访问地址
`kirby note recording-url <note_id>`	—	查询笔记录音链接
`kirby note pre-summary <note_id>`	—	查询预总结
`kirby note accurate-pre-summary <note_id>`	—	查询基于 ASR 的预总结
`kirby note outlines <note_id>`	—	查询转写大纲
`kirby note speakers <note_id>`	—	查询笔记说话人
`kirby note summary-config <note_id>`	—	查询总结配置
`kirby note task-status <note_id>`	—	查询笔记任务状态
`kirby note item <note_id>`	—	查询笔记列表项
`kirby note latest-task <note_id>`	`--task-type` *	按任务类型查询最新状态
`kirby note share-url <note_id>`	`--contents`	查询分享链接
`kirby note recent-speakers`	`--limit`	查询最近说话人
`kirby note audio-types`	—	查询支持的音频类型
`kirby note check-config <note_id>`	`--speaker-nums` / `--recording-language`	检测转录配置变化

bash

kirby note trans note_123

联系人管理12 个命令

权限：contacts:read

命令	选项	用途
`kirby contacts list`	`--page` / `--size` / `--keyword` / `--order`	分页列出联系人
`kirby contacts get <contact_id>`	—	获取联系人详情
`kirby contacts search`	`--name` * / `--limit`	模糊搜索联系人
`kirby contacts profile <contact_id>`	—	获取联系人档案详情
`kirby contacts insight <contact_id>`	—	获取联系人洞察
`kirby contacts conversations <contact_id>`	`--page` / `--size`	列出联系人的对话记录
`kirby contacts overview <contact_id>`	—	查询会话概览
`kirby contacts profile-detail <contact_id>`	—	查询静态画像
`kirby contacts tags <contact_id>`	—	查询联系人标签
`kirby contacts feature-audio <contact_id>`	—	查询特征音频
`kirby contacts profile-source <contact_id>`	`--section` * / `--key` * / `--uid`	查询画像字段来源
`kirby contacts insight-source`	`--asr-ids` / `--highlight-ids`	查询洞察来源

bash

kirby contacts overview contact_123

* 表示必填选项。完整参数说明可运行 kirby <模块> <命令> --help 查看。画像来源必须提供 --section 和 --key，洞察来源必须提供 --asr-ids 或 --highlight-ids。

Install

安装

一行命令的安装脚本，覆盖 macOS / Linux 主流 OS / arch，普通用户与 CI 都用它即可。

bash · install.sh

curl -fsSL https://static1.comu.com/kirby-cli/install.sh | sh

bash · version

kirby --version

脚本会自动探测 OS / arch、下载对应版本二进制并放到 /usr/local/bin/kirby（无写入权限时自动回退到 ~/.local/bin）；仅依赖 curl。

升级 / 卸载

重跑脚本即覆盖升级到最新版；卸载直接删二进制。

bash · upgrade

curl -fsSL https://static1.comu.com/kirby-cli/install.sh | sh

bash · uninstall

rm -f "$(command -v kirby)"

Usage

使用

快速命令、命令清单、高级用法、退出码、配置位置都在下面。

假设已有 kb_ 开头的 API Key（通过 Comu APP → 我的页面 → Developers → API Keys 获取）；下面命令按顺序执行即可，每条都能单独复制。

bash · 1 登录

printf '%s' "$KIRBY_API_KEY" | kirby login --api-key-stdin

bash · 2 接口清单

kirby spec list

bash · 3 调接口

kirby api POST /api/kirby/v1/note/paging --body '{"page":1,"pageSize":20}'

bash · 4 退出

kirby logout

命令清单

所有命令都支持全局 flag --profile / --output / --base-url / --verbose。

命令	关键 flag	用途
`kirby login`	`--api-key` / `--api-key-stdin` / `--browser`	登录。默认 API Key 模式；`--browser` 切到 OAuth 2.0 Device Flow。
`kirby logout`	—	清空当前 profile 凭据，撤销 refresh_token（Device Flow 模式下）。
`kirby whoami`	—	显示当前 profile、登录模式（api_key / browser）、user_id 等。
`kirby api <METHOD> <PATH>`	`--query k=v` / `--body` / `--body @file` / `--body -`	透传任意 HTTP 请求，自动注入 `Authorization: Bearer …`，状态码映射退出码。
`kirby spec list`	—	从 OpenAPI spec 拉接口清单（METHOD / PATH / SUMMARY），无需登录。
`kirby spec pull`	`--format yaml\|json` / `-o <file>`	拉完整 spec 到 stdout 或落到文件。
`kirby spec open`	`--print`	在浏览器里打开 spec 地址；`--print` 仅打印 URL 不真打开。
`kirby doctor`	—	诊断本机环境：网络可达性、配置文件、凭据完整性等。

bash · api 示例

kirby api POST /api/kirby/v1/note/paging --body '{"page":1,"pageSize":20}'

高级用法：Device Flow · 多 profile · 输出格式 · OpenAPI 发现

Device Flow（OAuth 2.0）

本机 / CI 没法贴 Key 时用浏览器授权；CLI 轮询 token 端点直到拿到 access_token。

bash

kirby login --browser \
  --client-id kirby-cli \
  --scope "note:read contacts:read action_items:read"

多 profile 隔离

用 --profile 在同一台机器上同时维护多套凭据，比如 prod / staging。

bash · staging login

kirby --profile staging login --api-key kb_staging_xxx

bash · staging spec

kirby --profile staging spec list

bash · staging api

kirby --profile staging api POST /api/kirby/v1/note/paging \
  --body '{"page":1,"pageSize":20}'

输出格式

--output 默认 auto —— TTY 给人看的 table，非 TTY 给程序看的 json。也可以强制指定。

bash · json

kirby --output json whoami

bash · table

kirby --output table whoami

bash · auto

kirby whoami

OpenAPI 发现

kirby spec 不需要登录即可查询；适合在 Agent 编排前先列出可用能力。

bash · list

kirby spec list

bash · pull json

kirby spec pull --format json

bash · pull file

kirby spec pull -o openapi.yaml

bash · open

kirby spec open

退出码契约

脚本 / Agent 严格按退出码分支即可，0..8 含义稳定。

Code	含义
`0`	成功
`1`	通用错误
`2`	网络错误（DNS / 连接 / 超时）
`3`	未登录或需要重新登录（API 返回 401，且 API Key 模式无法 refresh）
`4`	用户拒绝授权（Device Flow `access_denied`）
`5`	参数不合法（flag / argument 校验失败）
`6`	Device code 过期（Device Flow `expired_token`）
`7`	服务端 5xx
`8`	资源不存在（API 返回 404）

配置文件位置与环境变量

所有非敏感配置走 config.toml，敏感凭据走 credentials.json（权限 0600）。位置遵循 XDG，未设置 XDG_CONFIG_HOME 时回退到 $HOME/.config/kirby。

文件	说明
`$XDG_CONFIG_HOME/kirby/credentials.json`	多 profile 凭据。文件权限 `0600`，仅当前用户可读写。
`$XDG_CONFIG_HOME/kirby/config.toml`	非敏感配置，例如默认 `output` 等。

环境变量

变量	说明
`KIRBY_API_KEY`	常用于 `printf '%s' "$KIRBY_API_KEY" \| kirby login --api-key-stdin`。

命令行调接口

在哪些场景用

四个业务模块

安装

使用

环境变量