# gt: General Translation CLI tool: gt api-key create
URL: https://generaltranslation.com/en-GB/docs/cli/reference/commands/api-key-create.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Create a project API key with explicit permissions and print its secret once. API reference for the gt api-key create command.

Create runtime or automation credentials without changing local environment or config files. Authenticate with a saved login or an authorised explicit key as described in [Configuring the CLI](/docs/cli/guides/configuring#credentials).

## Overview [#overview]

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

| Parameter                                      | Description                       | Type       | Optional | Default                       |
| ---------------------------------------------- | --------------------------------- | ---------- | -------- | ----------------------------- |
| [`--name <name>`](#name)                       | Non-empty key name.               | `string`   | No       | —                             |
| [`--permission <permissions...>`](#permission) | Explicit canonical grants.        | `string[]` | No       | —                             |
| [`-c, --config <path>`](#config)               | Config file path.                 | `string`   | Yes      | Auto-resolved                 |
| [`--api-key <key>`](#api-key)                  | Explicit authentication override. | `string`   | Yes      | `GT_API_KEY`, otherwise login |
| [`--project-id <id>`](#project-id)             | Target project.                   | `string`   | Yes      | Config or environment         |

## How it works [#how-it-works]

The caller needs `project:api_keys:write` authorisation and permission to delegate every requested grant. Unavailable grants fail on an all-or-nothing basis; the CLI does not silently narrow the selection. Project keys cannot hold `project:api_keys:write` and cannot create other keys.

On success, only the new secret followed by a newline is written to stdout. Diagnostics go to stderr. The secret bypasses the logger and log file, even with `--quiet` or `GT_LOG_FORMAT=json`; it is not JSON metadata. The command does not write env or config files.

## Flags [#flags]

The [global options](/docs/cli/reference/global-options) also apply.

### Name

**Type** `string` · **Required** · **Default** —

The key&#39;s display name. Leading and trailing whitespace is trimmed; an empty result is rejected before any request is sent.

### Permission

**Type** `string[]` · **Required** · **Default** —

Pass one or more canonical permission names, separated by spaces or by repeating the flag:

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

Wildcards, preset names and key-type flags are not supported. Omitting permissions results in an error; it is not a shortcut to full access. Include each required grant explicitly, and do not assume that a write grant also confers read access.

### Config

**Type** `string` · **Optional** · **Default** Auto-resolved

Read project settings from this JSON config file; the `.json` suffix may be omitted. If this is not set, standard `gt.config.json` discovery applies.

### API key

**Type** `string` · **Optional** · **Default** `GT_API_KEY`, otherwise saved login

Override authentication with an explicit authorised key. Invalid or insufficient keys do not fall back to login. Prefer environment-based secrets over literal secrets in shell history. (See [credential precedence](/docs/cli/guides/configuring#credentials)).

### Project ID

**Type** `string` · **Optional** · **Default** Config or environment

Select the target project. A config ID that conflicts with the flag or resolved environment ID fails validation. Without a config ID, the flag takes precedence over the environment. Supported framework-prefixed project variables are also taken into account during resolution.

## Example [#example]

After signing in with [`gt login`](/docs/cli/reference/commands/login), create a generate-only development runtime key:

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

Store the returned secret securely. This generate-only key cannot run the full [`gt translate`](/docs/cli/reference/commands/translate) pipeline. For CI, grant permissions for the [whole workflow](/docs/cli/guides/configuring#credentials) and save the key in your CI provider&#39;s secret store, not in committed files.

<Callout type="warn">
  Treat stdout as secret material. Do not merge stderr into it, send it to shared logs, or expose even a generate-only key in deployed browser or mobile bundles. Repeating the command can create another key; there is no remote rollback or idempotent retry guarantee.
</Callout>

## Sitemap

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