📦 unkey-cli — unkey-命令行工具

Unkey 命令行工具 技能

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

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

何时使用

以下场景应触发本技能：

创建、查询、删除 API namespace 创建、校验、更新、删除 API keys 管理 identities（按用户/团队分组 key） 管理 权限s / 角色s（RBAC） 配置或排查 ratelimit 查询 key verification 分析（SQL） 用户明确要求使用 unkey 命令行 文档发现规则

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

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

再根据索引进入对应 命令行工具 子页面（如 docs/命令行工具/keys/创建-key.md）。

安装检查与安装

先检查是否已安装：

unkey --help

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

npm 安装 -g unkey

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

鉴权与密钥来源优先级

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

命令参数 --root-key 环境变量 UNKEY_ROOT_KEY 本地配置 ~/.unkey/config.toml（来自 unkey auth 记录in）

首次登录命令：

unkey auth 记录in

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

标准命令形态

所有 API 操作遵循：

unkey API [flags]

Resources APIs: API namespace 的创建、查询、删除、列 key keys: key 创建/校验/更新/删除、权限与角色绑定 identities: 身份 创建/查询/更新/删除 权限s: 权限 与 角色 管理 ratelimit: 限流检查与 override 管理 分析: SQL 查询 key verification 数据 常用命令示例 # 创建 API namespace unkey API APIs 创建-API --name=payment-服务-prod

# 创建 key unkey API keys 创建-key --API-id=API_1234abcd --name='Production Key' --enabled

# 校验 key unkey API keys 验证-key --key=sk_1234abcdef

# 单标识限流检查 unkey API ratelimit limit --namespace=API.请求s --identifier=user_123 --limit=100 --duration=60000

# 分析 查询 unkey API 分析 获取-verifications --查询="SELECT COUNT(*) as total FROM key_verifications_v1 WHERE outcome = 'VALID' AND time >= now() - INTERVAL 7 DAY"

# 创建 权限 并绑定到 key unkey API 权限s 创建-权限 --name=documents.read --slug=documents-read unkey API keys 添加-权限s --key-id=key_1234abcd --权限s=documents.read,documents.write

输出与脚本模式

默认输出通常包含：

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

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

unkey API APIs 创建-API --name=my-API --输出=json | jq '.data.id'

全局参数

所有命令都可使用：

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

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

unkey --help unkey API --help unkey API keys --help unkey API keys 创建-key --help

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

常见失败与建议：

authentication missing/forbidden: 检查 UNKEY_ROOT_KEY、--root-key、unkey auth 记录in API_not_found 或 key_not_found: 核对 API-id/key-id 是否属于当前 workspace workspace_rate_limited: 加退避重试并减少高频调用 invalid_分析_查询: 修复 SQL 语法，仅允许 SELECT 建议回复格式 # Unkey 命令行工具 执行结果

• command: <实际执行命令（脱敏后）>
• auth_source:
• 输出_mode:

结果

Next Step