This command is planned for a future release.
culvii key create
Create a new API key in the active tenant and environment.
Synopsis
culvii key create --name <name> [--workspace <slug>] [--scope <scope>] [--description <text>]
Description
Creates a new API key in the active tenant and environment. Requires an OAuth session — a key can never mint another key. The full secret is shown exactly once in the terminal output and cannot be retrieved again. Only the key's fingerprint is stored.
Keys are tenant-scoped resources. They survive user offboarding — a departed user's keys remain valid until explicitly revoked by a tenant admin.
Scope values: admin, developer, runner, read-only. Defaults to developer.
Delegate-down rule: you cannot mint a key with broader scope than your own permissions. A user with developer permissions cannot create an admin-scoped key.
Maximum 5 active (non-revoked) keys per workspace.
Flags
| Flag | Type | Description |
|---|---|---|
--name | string | Human-readable label, e.g. github-actions-deploy. Required. Non-empty. |
--workspace | string | Workspace slug to scope this key to. If omitted, the key is tenant-wide. Tenant-wide keys cannot be used with culvii dev. |
--scope | string | Capability level: admin, developer, runner, read-only. Default: developer. |
--description | string | Optional free-text note. |
Key prefix by environment
| Environment | Prefix | Example |
|---|---|---|
| dev | ck_dev_ | ck_dev_a3f9...8c2d |
| sandbox | ck_sandbox_ | ck_sandbox_a3f9...8c2d |
| prod | ck_live_ | ck_live_a3f9...8c2d |
The prefix is part of the secret string returned at creation. It is not stored in the database.
Examples
culvii key create --name github-actions-deploy --workspace payments --scope developer
# Output:
# Created key: github-actions-deploy
# Fingerprint: a3f9...8c2d
# Workspace: payments
# Scope: developer
#
# ⚠ Save this secret now. It will not be shown again.
# ck_dev_a3f9_<rest_of_secret>
Error behaviour
| Condition | Status | Message |
|---|---|---|
| Called with API key instead of OAuth | 403 | "A key cannot mint another key. Run culvii login first." |
| Invalid scope value | 400 | "Invalid scope. Valid values: admin, developer, runner, read-only" |
| Scope exceeds caller's permissions | 403 | "Cannot mint a key with greater scope than your own." |
| Active key limit reached | 409 | "Workspace has 5 active keys. Revoke one before creating another." |
| Not authenticated | 401 | "Run culvii login first." |
Related commands
culvii key list, culvii key rotate, culvii key revoke