{"skill":{"slug":"unkey-cli","displayName":"unkey-cli","summary":"使用 Unkey CLI 在终端中管理 API namespaces、keys、identities、permissions、rate limits 和 analytics 查询。当用户提到 unkey 命令、API key 管理、限流、RBAC 权限、身份分组或 key 验证排查时触发。Use this ski...","description":"---\nname: unkey-cli\ndescription: 使用 Unkey CLI 在终端中管理 API namespaces、keys、identities、permissions、rate limits 和 analytics 查询。当用户提到 unkey 命令、API key 管理、限流、RBAC 权限、身份分组或 key 验证排查时触发。Use this skill for Unkey CLI operations and troubleshooting.\nmetadata:\n  openclaw:\n    requires:\n      bins: [\"bash\", \"unkey\", \"jq\"]\nuser-invocable: true\nargument-hint: \"可选参数：resource, action, flags, output(json), root_key_source\"\n---\n\n# Unkey CLI Skill\n\n使用 Unkey 官方 CLI 在终端执行管理操作，不要臆造命令输出。\n\n> 注意：CLI 处于 early 阶段，命令和输出格式可能变化；底层 Unkey API 是稳定版本化的。\n\n## 何时使用\n\n以下场景应触发本技能：\n- 创建、查询、删除 API namespace\n- 创建、校验、更新、删除 API keys\n- 管理 identities（按用户/团队分组 key）\n- 管理 permissions / roles（RBAC）\n- 配置或排查 ratelimit\n- 查询 key verification analytics（SQL）\n- 用户明确要求使用 `unkey` 命令行\n\n## 文档发现规则\n\n在扩展命令细节（参数、边界行为）前，先读取文档索引：\n- `https://unkey.com/docs/llms.txt`\n\n再根据索引进入对应 CLI 子页面（如 `docs/cli/keys/create-key.md`）。\n\n## 安装检查与安装\n\n先检查是否已安装：\n\n```bash\nunkey --help\n```\n\n若未安装，优先提示以下方式之一：\n\n```bash\nnpm install -g unkey\n```\n\n或从 GitHub Releases 下载对应平台二进制。\n\n## 鉴权与密钥来源优先级\n\n执行命令前确认 root key 来源，优先级如下：\n1. 命令参数 `--root-key`\n2. 环境变量 `UNKEY_ROOT_KEY`\n3. 本地配置 `~/.unkey/config.toml`（来自 `unkey auth login`）\n\n首次登录命令：\n\n```bash\nunkey auth login\n```\n\n如果三者都没有，停止执行并提示用户提供 root key 或先登录。\n\n## 标准命令形态\n\n所有 API 操作遵循：\n\n```bash\nunkey api <resource> <action> [flags]\n```\n\n### Resources\n\n- `apis`: API namespace 的创建、查询、删除、列 key\n- `keys`: key 创建/校验/更新/删除、权限与角色绑定\n- `identities`: identity 创建/查询/更新/删除\n- `permissions`: permission 与 role 管理\n- `ratelimit`: 限流检查与 override 管理\n- `analytics`: SQL 查询 key verification 数据\n\n## 常用命令示例\n\n```bash\n# 创建 API namespace\nunkey api apis create-api --name=payment-service-prod\n\n# 创建 key\nunkey api keys create-key --api-id=api_1234abcd --name='Production Key' --enabled\n\n# 校验 key\nunkey api keys verify-key --key=sk_1234abcdef\n\n# 单标识限流检查\nunkey api ratelimit limit --namespace=api.requests --identifier=user_123 --limit=100 --duration=60000\n\n# analytics 查询\nunkey api analytics get-verifications --query=\"SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL 7 DAY\"\n\n# 创建 permission 并绑定到 key\nunkey api permissions create-permission --name=documents.read --slug=documents-read\nunkey api keys add-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write\n```\n\n## 输出与脚本模式\n\n默认输出通常包含：\n- 请求 ID 和耗时（例如 `req_xxx (took 45ms)`）\n- 返回数据对象\n\n用于脚本时，强制使用 JSON：\n\n```bash\nunkey api apis create-api --name=my-api --output=json | jq '.data.id'\n```\n\n## 全局参数\n\n所有命令都可使用：\n- `--root-key`: 覆盖 root key\n- `--api-url`: 覆盖 API 地址（默认 `https://api.unkey.com`）\n- `--config`: 指定配置文件路径（默认 `~/.unkey/config.toml`）\n- `--output`: 输出格式（脚本场景建议 `json`）\n\n## 帮助与自检\n\n优先使用内置帮助确定 flags：\n\n```bash\nunkey --help\nunkey api --help\nunkey api keys --help\nunkey api keys create-key --help\n```\n\n## 执行准则\n\n- 在未确认鉴权来源前，不执行会修改资源的命令。\n- 对删除类命令（二次不可逆）先提醒用户确认再执行。\n- 不回显完整 root key；如需展示命令，脱敏处理密钥。\n- 不伪造执行结果；失败时返回原始错误并给出下一步修复建议。\n\n## 失败处理\n\n常见失败与建议：\n- `authentication missing/forbidden`: 检查 `UNKEY_ROOT_KEY`、`--root-key`、`unkey auth login`\n- `api_not_found` 或 `key_not_found`: 核对 `api-id`/`key-id` 是否属于当前 workspace\n- `workspace_rate_limited`: 加退避重试并减少高频调用\n- `invalid_analytics_query`: 修复 SQL 语法，仅允许 `SELECT`\n\n## 建议回复格式\n\n```markdown\n# Unkey CLI 执行结果\n- command: <实际执行命令（脱敏后）>\n- auth_source: <flag | env | config>\n- output_mode: <default | json>\n\n## Result\n<关键输出/对象>\n\n## Next Step\n<一个可执行的后续动作>\n```\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":348,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1777819096839,"updatedAt":1778492838254},"latestVersion":{"version":"1.0.1","createdAt":1777819190594,"changelog":"No changes detected in this version.\n\n- Version 1.0.1 does not introduce any file or documentation updates.","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"kyriswu","userId":"s17adkk1pw6rdbxdzht0y1pey583gqfs","displayName":"kyris wu","image":"https://avatars.githubusercontent.com/u/5120703?v=4"},"moderation":null}