unkey-cli

使用 Unkey CLI 在终端中管理 API namespaces、keys、identities、permissions、rate limits 和 analytics 查询。当用户提到 unkey 命令、API key 管理、限流、RBAC 权限、身份分组或 key 验证排查时触发。Use this skill for Unkey CLI operations and troubleshooting.

Unkey CLI Skill

使用 Unkey 官方 CLI 在终端执行管理操作，不要臆造命令输出。

注意：CLI 处于 early 阶段，命令和输出格式可能变化；底层 Unkey API 是稳定版本化的。

何时使用

以下场景应触发本技能：

• 创建、查询、删除 API namespace
• 创建、校验、更新、删除 API keys
• 管理 identities（按用户/团队分组 key）
• 管理 permissions / roles（RBAC）
• 配置或排查 ratelimit
• 查询 key verification analytics（SQL）
• 用户明确要求使用 unkey 命令行

文档发现规则

在扩展命令细节（参数、边界行为）前，先读取文档索引：

• https://unkey.com/docs/llms.txt

再根据索引进入对应 CLI 子页面（如 docs/cli/keys/create-key.md）。

安装检查与安装

先检查是否已安装：

unkey --help

若未安装，优先提示以下方式之一：

npm install -g unkey

或从 GitHub Releases 下载对应平台二进制。

鉴权与密钥来源优先级

执行命令前确认 root key 来源，优先级如下：

1. 命令参数 --root-key
2. 环境变量 UNKEY_ROOT_KEY
3. 本地配置 ~/.unkey/config.toml（来自 unkey auth login）

首次登录命令：

unkey auth login

如果三者都没有，停止执行并提示用户提供 root key 或先登录。

标准命令形态

所有 API 操作遵循：

unkey api <resource> <action> [flags]

Resources

• apis: API namespace 的创建、查询、删除、列 key
• keys: key 创建/校验/更新/删除、权限与角色绑定
• identities: identity 创建/查询/更新/删除
• permissions: permission 与 role 管理
• ratelimit: 限流检查与 override 管理
• analytics: SQL 查询 key verification 数据

常用命令示例

# 创建 API namespace
unkey api apis create-api --name=payment-service-prod

# 创建 key
unkey api keys create-key --api-id=api_1234abcd --name='Production Key' --enabled

# 校验 key
unkey api keys verify-key --key=sk_1234abcdef

# 单标识限流检查
unkey api ratelimit limit --namespace=api.requests --identifier=user_123 --limit=100 --duration=60000

# analytics 查询
unkey api analytics get-verifications --query="SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL 7 DAY"

# 创建 permission 并绑定到 key
unkey api permissions create-permission --name=documents.read --slug=documents-read
unkey api keys add-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write

输出与脚本模式

默认输出通常包含：

• 请求 ID 和耗时（例如 req_xxx (took 45ms)）
• 返回数据对象

用于脚本时，强制使用 JSON：

unkey api apis create-api --name=my-api --output=json | jq '.data.id'

全局参数

所有命令都可使用：

• --root-key: 覆盖 root key
• --api-url: 覆盖 API 地址（默认 https://api.unkey.com）
• --config: 指定配置文件路径（默认 ~/.unkey/config.toml）
• --output: 输出格式（脚本场景建议 json）

帮助与自检

优先使用内置帮助确定 flags：

unkey --help
unkey api --help
unkey api keys --help
unkey api keys create-key --help

执行准则

• 在未确认鉴权来源前，不执行会修改资源的命令。
• 对删除类命令（二次不可逆）先提醒用户确认再执行。
• 不回显完整 root key；如需展示命令，脱敏处理密钥。
• 不伪造执行结果；失败时返回原始错误并给出下一步修复建议。

失败处理

常见失败与建议：

• authentication missing/forbidden: 检查 UNKEY_ROOT_KEY、--root-key、unkey auth login
• api_not_found 或 key_not_found: 核对 api-id/key-id 是否属于当前 workspace
• workspace_rate_limited: 加退避重试并减少高频调用
• invalid_analytics_query: 修复 SQL 语法，仅允许 SELECT

建议回复格式

# Unkey CLI 执行结果
- command: <实际执行命令（脱敏后）>
- auth_source: <flag | env | config>
- output_mode: <default | json>

## Result
<关键输出/对象>

## Next Step
<一个可执行的后续动作>