# gt: General Translation CLI tool: gt api-key create
URL: https://generaltranslation.com/zh/docs/cli/reference/commands/api-key-create.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 创建具有明确Permission的项目 API 密钥，其 secret 仅输出一次。gt api-key create 命令的 API 参考。

创建运行时或自动化凭据，无需更改本地环境或配置文件。请按照[配置 CLI](/docs/cli/guides/configuring#credentials) 中的说明，使用已保存的登录会话或已获授权的显式密钥进行身份验证。

## 概览 [#overview]

```bash
npx gt api-key create --name <name> --permission <permissions...> [options]
```

| 参数                                             | 说明                | 类型         | 可选 | 默认值                   |
| ---------------------------------------------- | ----------------- | ---------- | -- | --------------------- |
| [`--name <name>`](#name)                       | 非空的密钥名称。          | `string`   | 否  | —                     |
| [`--permission <permissions...>`](#permission) | 显式指定的规范授权项。       | `string[]` | 否  | —                     |
| [`-c, --config <path>`](#config)               | 配置文件路径。           | `string`   | 是  | 自动解析                  |
| [`--api-key <key>`](#api-key)                  | 显式指定身份验证凭据，覆盖默认值。 | `string`   | 是  | `GT_API_KEY`，否则使用登录凭据 |
| [`--project-id <id>`](#project-id)             | 目标项目。             | `string`   | 是  | 取自配置或环境变量             |

## 工作原理 [#how-it-works]

调用方需要具备 `project:api_keys:write` 授权，并且有权委派所请求的每一项 授权项。授权项 的校验遵循“全有或全无”原则：只要有任何一项不可用，整个操作即失败；CLI 不会静默缩小所选范围。项目密钥不能持有 `project:api_keys:write`，也无法创建其他密钥。

成功时，只会向 stdout 写入新的 secret 及一个换行符。诊断信息则输出到 stderr。secret 不经过日志记录器，也不会写入日志文件，即使使用 `--quiet` 或 `GT_LOG_FORMAT=json` 也是如此；它不属于 JSON 元数据。该命令不会写入 env 文件或配置文件。

## 选项 [#flags]

[全局选项](/docs/cli/reference/global-options)同样适用。

### 名称

**类型** `string` · **必填** · **默认值** —

该 密钥 的显示名称。首尾空白字符会被自动去除；若去除后为空，则会在发送请求前直接拒绝。

### Permission

**类型** `string[]` · **必填** · **默认值** —

传入一个或多个规范 permission 名称，可用空格分隔，也可多次重复使用该选项：

* `project:write`
* `project:context:read`
* `project:context:write`
* `project:files:read`
* `project:files:write`
* `project:translations:generate`
* `project:translations:enqueue`

不支持通配符、预设名称和密钥类型选项。省略 permissions 会直接报错，而不会作为授予完全访问权限的快捷方式。请显式列出所需的每项授权项；不要默认写入授权项会同时包含读取权限。

### 配置

**类型** `string` · **可选** · **默认值** 自动解析

从指定的 JSON 配置文件读取项目设置，可省略 `.json` 后缀。未指定时，按常规方式查找 `gt.config.json`。

### API Key

**类型** `string` · **可选** · **默认值** `GT_API_KEY`，若未设置则使用已保存的登录信息

使用显式指定的已授权密钥覆盖默认的身份验证方式。密钥无效或Permission不足时，不会回退到登录信息。建议通过环境变量提供密钥，避免在命令中直接写入密钥而留存在 shell 历史记录中。 (参见[凭据优先级](/docs/cli/guides/configuring#credentials)) 。

### 项目 ID

**类型** `string` · **可选** · **默认值** 配置或环境变量

指定目标项目。如果配置中的 ID 与选项值或解析出的环境变量 ID 不一致，验证将失败。如果配置中未指定 ID，则选项优先于环境变量。受支持的带框架前缀的项目变量也会参与解析。

## 示例 [#example]

使用 [`gt login`](/docs/cli/reference/commands/login) 登录后，创建一个仅用于生成 (generate-only) 的开发环境运行时密钥：

```bash
npx gt api-key create \
  --project-id your-project-id \
  --name "Runtime translations" \
  --permission project:translations:generate
```

请妥善保管返回的 secret。此密钥仅限生成，无法运行完整的 [`gt translate`](/docs/cli/reference/commands/translate) 流水线。在 CI 中，请为[整个工作流](/docs/cli/guides/configuring#credentials)授予Permission，并将密钥保存在 CI 服务商的 secret 存储中，切勿写入会被提交的文件。

<Callout type="warn">
  请将 stdout 视为机密内容。不要将 stderr 合并到 stdout，不要将其输出到共享日志，也不要在已部署的浏览器或移动端 bundle 中暴露任何密钥，即使是仅限生成的密钥也不行。重复执行该命令可能会再创建一个密钥；系统不支持远程回滚，也不保证重试具有幂等性。
</Callout>

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.