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）。

安装检查与安装#

先检查是否已安装：

bash

unkey --help

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

bash

npm install -g unkey

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

鉴权与密钥来源优先级#

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

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

首次登录命令：

bash

unkey auth login

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

标准命令形态#

所有 API 操作遵循：

bash

unkey api <resource> <action> [flags]

Resources#

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

常用命令示例#

bash

# 创建 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：

bash

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：

bash

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

建议回复格式#

markdown

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

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

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