@keepclaw/keep-cli

Keep 命令行工具 —— 在终端完成 Keep 登录、健康记录与 MCP 工具调用。

与 @keepclaw/keep-record Skill 共享同一份凭证（~/.keepai/.env）， 一处登录两处可用：在 OpenClaw / Hermes 里用 Skill，或在 shell / CI 里用 CLI。

安装

npm install -g @keepclaw/keep-cli
keep --version

安装

# 正式用户
npm install -g @keepclaw/keep-cli

# 连接自定义 MCP server
export KEEP_MCP_URL=https://mcp.example.com/... && npm install -g @keepclaw/keep-cli

安装时 postinstall 脚本会把 MCP server 地址写入 ~/.keepai/.env（key: KEEP_MCP_URL，与环境变量同名）。若地址与已存储值相同则幂等；若地址变化则同时清空旧凭证，需要重新 keep login。

快速开始

# 扫码登录（凭证写入 ~/.keepai/.env，权限 0600）
keep login

# 查看状态
keep status

# 记录一条饮食（支持所有健康类型：饮食/运动/体重/围度/睡眠/生理期）
keep record "午餐吃了鸡胸肉沙拉"

# 带图片（本地文件自动上传，也可直接传 URL）
keep record "午餐" --image=./lunch.jpg
keep record "午餐" --image=https://example.com/a.jpg

# 强制指定记录类型（跳过服务端自动识别）
keep record "跑了 5km" --type=exercise

# 查询Keep的数据或统计
keep query "查一下我最近一次体重"
keep query "我最近 7 天跑步情况"

# 退出登录（服务端 revoke + 本地清理）
keep logout

# 自检
keep doctor

命令

| 命令 | 说明 | |------|------| | keep login | 扫码登录（终端绘制 ASCII 二维码 + 轮询） | | keep logout | 调 revoke_auth 并清理 ~/.keepai/.env | | keep status / keep whoami | 查看当前登录状态与 token 过期时间（含当前 MCP URL） | | keep record <text> | 记录健康数据，可选 --image / --type | | keep query <text> | 查询健康数据，支持最近一次、最近 N 天统计等自然语言查询 | | keep tools list | 列出 MCP 暴露的工具（开发者向） | | keep tools call <name> '<json>' | 调用任意 MCP 工具，支持位置参数或 --stdin | | keep doctor | 自检：Node 版本、凭证文件、MCP 连通性 |

全局选项

| 选项 | 说明 | |------|------| | --json | 机器可读输出：stdout 全 JSON envelope | | --url <url> | 覆盖 MCP Server 根地址 | | -v, --version | 打印版本 |

输出契约

stdout = 数据，stderr = 进度/提示/警告。 请放心管道：

keep --json status | jq .data.logged_in
keep --json record "..." 2>/dev/null | jq .data

JSON envelope：

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "..." } }

退出码

| 码 | 含义 | |----|------| | 0 | 成功 | | 1 | 业务错误（RATE_LIMITED / UPSTREAM_ERROR / 其他 Keep 错误码） | | 2 | 用法错误 / 参数无效（INVALID_PARAM） | | 3 | 网络 / IO 错误（TRANSPORT_ERROR） | | 4 | 鉴权错误（AUTH_REQUIRED / TOKEN_EXPIRED） |

环境变量

| 变量 | 说明 | 默认 | |------|------|------| | keep_auth_token | JWT（优先级高于 ~/.keepai/.env） | — | | keep_auth_token_expired | token 过期 Unix 时间戳 | — | | keep_username | 登录用户名（登录成功后写入 ~/.keepai/.env） | — | | KEEP_MCP_URL | 覆盖 MCP 地址（等同 --url） | https://mcp.gotokeep.com/skills-mcp-gateway-page/v1 | | KEEP_TELEMETRY | 调用埋点；0 / false / off / no 关闭。上报体里 source=keep-cli，与 keep-record 技能 exec 路径区分 | 开启 |

URL 优先级（运行时）：--url CLI 选项 > process env KEEP_MCP_URL > ~/.keepai/.env 的 KEEP_MCP_URL > 内置默认值

与 Skill 的关系

• keep login 写入的凭证可直接被 @keepclaw/keep-record Skill（在 OpenClaw / Hermes 里）读取使用
• keep logout 清除的凭证会同步失效所有入口
• 任何时候都可以通过 @keepclaw/skill-sdk 在自己的 Node 代码里复用相同能力

许可

MIT