Keep 0.54.3 常用 CLI 命令与工具详解
Keep（keephq/keep）0.54.3 官方 CLI 全命令实测：安装与连接、alert 查询/富化、provider 管理、workflow 部署与手动执行，含 4 个实测 bug 与 REST API 兜底方案。
Keep 0.54.3 常用 CLI 命令与工具详解
目标：完整实测 Keep（keephq/keep，开源 AIOps 告警管理平台）0.54.3 官方 CLI（
keep命令）的全部常用子命令：安装与连接配置、告警查询/富化、provider 管理、workflow 部署与手动执行，并沉淀 0.54.3 版本 CLI 的 4 个实测 bug 与 REST API 兜底方案。所有命令与回显均逐条实测（2026-10-23，CLI 与后端同为 0.54.3）。平台部署见 《Keep Docker Compose 部署指南》。
一、环境信息
| 项目 | 值 | 说明 |
|---|---|---|
| CLI 版本 | 0.54.3（keep version 实测） | 与后端 keep-api 同版本 |
| 后端版本 | v0.54.3（Compose 栈） | 部署见部署指南 |
| CLI 运行形态 | 官方 keep-cli 容器镜像（内含 Python 3.11 venv） | us-central1-docker.pkg.dev/keephq/keep/keep-cli |
| 连接方式 | 环境变量 KEEP_API_KEY + KEEP_API_URL（实测）或 ~/.keep.yaml 配置文件 | |
| 实测数据 | 2 条 demo 告警、3 个 workflow、3 个已安装 provider | 实测栈状态 |
二、工具概览
keep CLI 是 Keep 平台的命令行客户端，覆盖告警查询与富化、provider 连接管理、workflow 部署与触发、本地配置四类日常操作。顶层命令树（keep --help 实测）：
Usage: keep [OPTIONS] COMMAND [ARGS]...
Run Keep CLI.
Options:
-v, --verbose Enable verbose output.
-j, --json Enable json output.
-c, --keep-config TEXT The path to the keep config file (default
/root/.keep.yaml
--help Show this message and exit.
Commands:
alert Manage alerts.
api Start the API.
auth Manage auth.
config Manage the config.
extraction Manage extractions.
mappings Manage mappings.
provider Manage providers.
version Get the library version.
whoami Verify the api key auth.
workflow Manage workflows.
命令分组说明：alert（告警）、provider（集成）、workflow（工作流）是三大主力；config/whoami/version 管连接与版本；api 用于以进程方式直接拉起一个 API 服务（与容器化部署二选一）；auth/extraction/mappings 分别管理认证、提取规则与映射规则（本文以主力命令实测为主）。
三、前置条件
3.1 CLI 安装（三种方式）
方式一：官方 keep-cli 镜像（推荐，免安装）：
docker run --rm \
--network keep-0543-net \
-e KEEP_API_KEY=q1w2e3r4-keep-demo-key \
-e KEEP_API_URL=http://keep-backend:8080 \
us-central1-docker.pkg.dev/keephq/keep/keep-cli keep version
实测回显：
0.54.3
方式二：源码安装（需要与后端版本一致的代码）：
git clone --depth 1 --branch 0.54.3 https://github.com/keephq/keep.git
pip3 install ./keep/keep/
keep version
方式三（避坑）：PyPI 包现状。PyPI 上 keep 包（2.11）是与 Keep 平台无关的同名包，不要安装；官方曾经发布的 keephq 包已停更在 0.2.7，同样不代表 0.54.3 CLI。想用 pip 就走方式二的源码路径。
3.2 连接配置
CLI 需要两个参数：后端地址与 API Key。两种给法（实测均可）：
环境变量（本篇全部实测采用此方式）：
export KEEP_API_URL=http://<后端地址>:8080
export KEEP_API_KEY=<你的APIKey>
配置文件（keep config new 交互生成 ~/.keep.yaml，实测内容）：
api_key: q1w2e3r4-keep-demo-key
keep_api_url: http://keep-backend:8080
random_user_id: c72e14f0-87d7-43f4-84f0-d5097b79dbdc
验证连通（keep whoami 实测回显）：
Using keep api url: http://keep-backend:8080
Api key valid
{'tenant_id': 'keep'}
四、各工具详解
以下每个命令均在实测栈逐条执行。为省篇幅，统一省略每条命令前的容器包装（下称「包装头」，即方式一的 docker run 前缀），并省略 CLI 每次打印的无害告警行：
Using keep api url: http://keep-backend:8080
4.1 keep version / keep whoami
keep version # 输出 CLI 版本号：0.54.3
keep whoami # 验证 API Key 有效性（回显见 3.2）
4.2 keep config —— 本地配置管理
keep config new # 交互式生成 ~/.keep.yaml
keep config show # 查看当前配置
config show 实测回显（环境变量方式下本地文件为空，只有匿名 ID）：
Current config
random_user_id: 2b185cec-98eb-43dc-b397-ff6b8b406421
注意：
config只管 CLI 自己的连接参数，不影响服务端任何行为。
4.3 keep alert —— 告警查询与富化
列出告警（实测回显，两条实测告警）：
keep alert list
+----------------+------------------+--------------------------------+----------+--------+-------------+---------+----------+--------------------------+
| ID | Fingerprint | Name | Severity | Status | Environment | Service | Source | Last Received |
+----------------+------------------+--------------------------------+----------+--------+-------------+---------+----------+--------------------------+
| demo-alert-001 | disk-web-prod-01 | disk usage on web-prod-01 | critical | firing | None | None | ['demo'] | 2026-10-23T01:19:30.581Z |
| | | above 90% | | | | | | |
| demo-alert-002 | disk-db-prod-02 | disk usage on db-prod-02 above | critical | firing | None | None | ['demo'] | 2026-10-23T01:24:58.577Z |
| | | 95% | | | | | | |
+----------------+------------------+--------------------------------+----------+--------+-------------+---------+----------+--------------------------+
按属性过滤（--filter 支持按告警字段过滤，实测 severity=critical 返回全部两条 critical 告警，表格同上）：
keep alert list --filter severity=critical
按 fingerprint 查详情（实测输出完整告警 JSON，此处摘录核心字段）：
keep alert get disk-db-prod-02
{
"id": "demo-alert-002",
"name": "disk usage on db-prod-02 above 95%",
"status": "firing",
"severity": "critical",
"lastReceived": "2026-10-23T01:24:58.577Z",
"firingCounter": 1,
"isFullDuplicate": false,
"isPartialDuplicate": false,
"source": ["demo"],
"message": "Disk usage on /data of db-prod-02 is 96%",
"fingerprint": "disk-db-prod-02",
...
}
isFullDuplicate/isPartialDuplicate/duplicateReason 字段即告警去重机制的数据落点（去重原理见 《Keep 介绍与选型指南》）。
富化告警（给告警追加自定义字段，PARAMS 为 key=value 形式的可变参数，实测）：
keep alert enrich --fingerprint disk-db-prod-02 owner=sre-team ticket=INC-1024
Alert disk-db-prod-02 enriched successfully
复查富化结果（keep alert get disk-db-prod-02 中实测可见）：
"enriched_fields": ["owner", "ticket"],
"ticket": "INC-1024",
"owner": "sre-team"
模拟告警（keep alert simulate -p <provider类型>，实测 console provider 不支持模拟，如实记录）：
keep alert simulate -p console
Simulating alert
Provider does not support alert simulation
实测结论：simulate 能力依赖 provider 自身实现，console/webhook 均返回不支持；需要「造一条告警」时用 API POST /alerts/event 或 CLI 富化已有告警替代。
4.4 keep provider —— 集成连接管理
列出已安装连接（实测回显，Installed by 列区分 system 预置与手工连接，预置机制见《Keep 0.54.3 配置参数详解》）：
keep provider list
+----------------------------------+---------+-------------------+--------------+----------------------------+
| ID | Type | Name | Installed by | Installation time |
+----------------------------------+---------+-------------------+--------------+----------------------------+
| f92d7d3a4d754024b3c289db4b1eb43d | bash | bash-local | system | 2026-10-23T01:32:42.603161 |
| 09f66d0f96634ec8b9bd3c575d427ce4 | console | console-demo | admin@keephq | 2026-10-23T01:24:16.787161 |
| 03092072a8ab409ba41974670f4e7040 | console | console-yaml-prov | system | 2026-10-23T01:32:42.597398 |
+----------------------------------+---------+-------------------+--------------+----------------------------+
列出全部可用 provider 类型（实测 124 种，此处摘录前几行）：
keep provider list -a
+----------------------+---------------------------------------------------------------+
| Provider | Description |
+----------------------+---------------------------------------------------------------+
| airflow | Enrich alerts with data sent from Airflow. |
| aks | Enrich alerts using data from AKS. |
| amazonsqs | Sends and receive alerts from AmazonSQS. |
| anthropic | |
+----------------------+---------------------------------------------------------------+
连接一个 provider（无凭据类型可直接连接；需凭据的类型会在交互中追问）：
keep provider connect console # 直接跑会报错，见下
keep provider connect console --provider-name console-demo
第一次不带 --provider-name 的实测报错：
Error: Missing option '--provider-name'.
补上后实测回显（返回的连接 ID 即 provider ID，workflow 里 {{ providers.名称 }} 引用的就是它）：
+----------------------------------+---------+--------------+
| ID | Type | Name |
+----------------------------------+---------+--------------+
| 09f66d0f96634ec8b9bd3c575d427ce4 | console | console-demo |
+----------------------------------+---------+--------------+
4.5 keep workflow —— 工作流部署与触发
子命令树（keep workflow --help 实测）：
Commands:
apply Apply a workflow or multiple workflows from a directory.
list List workflows.
run Run a workflow with a specified ID and fingerprint.
runs Manage workflows executions.
apply：从 YAML 文件部署 workflow（实测）：
keep workflow apply --file /tmp/df-check.yml
Workflow /tmp/df-check.yml applied successfully
不带 --file 的实测报错：Error: Missing option '--file' / '-f'.；--file 也可指向目录批量 apply。
list：列出 workflow（实测 3 条：2 个系统预置 + 1 个 apply 部署；Last Execution Status 实测为 success）：
keep workflow list
+--------------------------------------+-----------------------+---------------------------------------------------------------------------------+----------+--------------+----------------------------+----------------------------+---------------------------+-----------------------+
| ID | Name | Description | Revision | Created By | Creation Time | Update Time | Last Execution Time | Last Execution Status |
+--------------------------------------+-----------------------+---------------------------------------------------------------------------------+----------+--------------+----------------------------+----------------------------+---------------------------+-----------------------+
| ecc524d1-a07e-4a93-a2d9-daeec421cc69 | Interval Logger | Print a heartbeat log every 10 seconds to verify the scheduler. | 1 | system | 2026-10-23T01:51:36.567436 | 2026-10-23T01:51:36.567397 | 1970-01-01T00:00:00+00:00 | success |
| 67853621-ef4f-4358-b7bf-80e3ee3a5341 | Disk Free Check | Run df on the Keep server and print the result to console. | 2 | admin@keephq | 2026-10-23T01:33:53.290454 | 2026-10-23T01:34:39.559858 | 1970-01-01T00:00:00+00:00 | success |
| bb3609cb-f9d1-457a-be34-652cf17414c4 | Disk Critical Handler | Handle critical disk alerts, log via console and enrich with owner and runbook. | 2 | admin@keephq | 2026-10-23T01:24:43.703065 | 2026-10-23T01:32:42.611626 | 1970-01-01T00:00:00+00:00 | success |
+--------------------------------------+-----------------------+---------------------------------------------------------------------------------+----------+--------------+----------------------------+----------------------------+---------------------------+-----------------------+
run：手动触发一次 workflow。0.54.3 的实测规则（两条坑都在这里）：
# 坑 1：--workflow-id 必须用 list 里的平台 UUID，不能写 YAML 里的 workflow.id
# 坑 2：--fingerprint 必填（绑定一次告警上下文），缺了直接报错
keep workflow run --workflow-id bb3609cb-f9d1-457a-be34-652cf17414c4 --fingerprint disk-db-prod-02
实测回显：
Workflow bb3609cb-f9d1-457a-be34-652cf17414c4 run successfully
Workflow Run ID 92e49f24-e740-4123-9473-a1ed387e3e40
错误示范实测（用名称跑，被当成多余参数）：
Error: Got unexpected extra arguments (Critical Handler)
缺 fingerprint 实测报错：
Error: Missing option '--fingerprint'.
Run ID 即执行实例标识，可用于 runs logs <RunID> 查日志（见下，0.54.3 该命令有 bug）与 API GET /workflows/executions 对照。
runs：执行记录管理（0.54.3 CLI 有 bug）。两个子命令实测均抛异常：
keep workflow runs list
File "/venv/lib/python3.11/site-packages/keep/cli/cli.py", line 592, in list_workflow_executions
raise Exception(f"Error getting workflow executions: {resp.text}")
Exception: Error getting workflow executions: {"detail":"Not Found"}
keep workflow runs logs 6c4e49d6-b0f1-4785-a48c-11d9df630ffa
File "/venv/lib/python3.11/site-packages/keep/cli/cli.py", line 646, in get_workflow_execution_logs
raise Exception(f"Error getting workflow executions: {resp.text}")
Exception: Error getting workflow executions: {"detail":"Not Found"}
根因：0.54.3 CLI 调用了不存在的 API 路径（/workflows/executions/list 等），后端实际端点是 GET /workflows/executions（版本错位 bug，非配置问题）。兜底方案（实测有效）：
curl -s -H "x-api-key: q1w2e3r4-keep-demo-key" "http://localhost:8148/workflows/executions?limit=5"
实测返回（JSON 数组，关键字段）：
[
{
"workflow_id": "67853621-ef4f-4358-b7bf-80e3ee3a5341",
"workflow_execution_id": "6c4e49d6-b0f1-4785-a48c-11d9df630ffa",
"alert_fingerprint": "disk-db-prod-02",
"workflow_status": "success",
"workflow_started": "2026-10-23T01:34:45.745275",
"event_id": "ec05470a-085b-4aff-ab3f-421bc790c5be"
}
]
五、注意事项
- CLI 版本与后端版本对齐：CLI 从源码安装时选与后端相同的 tag（如 0.54.3），混搭不同大版本最容易出现本篇 4.5 节的端点错位类异常。
--workflow-id的语义陷阱：CLI 与 API 的 workflow ID 都是平台分配的 UUID（keep workflow list第一列），YAML 里的workflow.id（如 disk-critical-handler）只是业务标识，手动执行时不要混用。- workflow
run的执行入口是异步的：命令返回 Run ID 不代表已跑完；interval/alert 触发的执行详情看后端容器日志或GET /workflows/executions（实测 0.54.3 的 executions 列表不含 interval 触发的执行，验证 interval workflow 以容器日志为准，详见配置参数详解篇 7.5）。 keep alert simulate不是通用测试器：能否模拟取决于 provider 是否实现该能力，与 provider 是否已连接无关（实测 console 已连接仍提示不支持）。- 全局选项
-j（JSON 输出）：脚本化解析时给命令加-j（如keep -j alert list），比解析表格稳定；-v输出调试日志。 - API Key 权限：CLI 能做的事 = Key 对应角色的 scope（预置
admin角色全量可用；webhook角色仅能上报告警）。
六、常见问题
6.1 docker 跑 keep-cli 报 exec not found：docker run ... keep-cli version 会报 exec: "version": executable file not found——镜像入口是裸 python3，命令必须写成 keep-cli keep version（keep 前缀不能省）。
6.2 PyPI 装错包：pip install keep 装到同名无关包；pip install keephq 是停更的旧包。正确路径见 3.1 方式二。
6.3 keep workflow runs list/runs logs 报 Not Found：0.54.3 CLI bug（调用了不存在端点），用 GET /workflows/executions API 兜底（回显见 4.5 节）；升级到修复版本后恢复。
6.4 keep alert list --export 导出空文件：0.54.3 实测 --export 生成的 JSON 文件为 0 字节。兜底方案用 REST API 导出：
curl -s -H "x-api-key: $KEEP_API_KEY" "http://<后端地址>:8080/alerts" -o alerts.json
6.5 keep provider connect 报 Missing --provider-name：connect 必须显式给连接名（见 4.4 实测），名称即 workflow 里 {{ providers.<名称> }} 的引用键。
6.6 whoami 报 No api key found：环境变量与配置文件都没给 Key。检查 KEEP_API_KEY 是否在当前 shell 生效，或执行 keep config new 落配置文件。
七、参考链接
- 官方 CLI 文档：https://docs.keephq.dev/cli/overview
- CLI 安装文档：https://docs.keephq.dev/cli/installation
- REST API 文档（兜底与 CLI 同源）：后端
http://<后端地址>:8080/docs（FastAPI 自动生成） - keephq/keep 仓库：https://github.com/keephq/keep
- 相关篇目：《Keep 介绍与选型指南》、《Keep Docker Compose 部署指南》、《Keep 0.54.3 配置参数详解》