culvii key create

Create a new API key.

Synopsis

culvii key create --name <name> --workspace <slug> --scope <scope> [--env <env>] [--save]

Description

Creates a new API key scoped to a workspace. Requires an OAuth session — a key can never mint another key. The full secret is shown exactly once and cannot be retrieved again. Only the fingerprint is stored.

--workspace takes a slug (not a UUID) and resolves it internally.

Delegate-down rule: you cannot mint a key with broader scope than your own permissions.

Limit: maximum 5 active (non-revoked) keys per workspace.

Flags

Flag	Required	Description
--name	✓	Human-readable label, e.g. github-actions-deploy.
--workspace	✓	Workspace slug to scope this key to.
--scope	✓	admin, developer, runner, or read-only.
--env	—	Target environment. Defaults to active context.
--save	—	Write the secret to ~/.culvii/config as the active API key.

Examples

culvii key create --name github-actions --workspace payments --scope developer
# → ⚠ Save this secret now. It will NOT be shown again.
# → Secret: ck_dev_abc123...
# → Fingerprint: a3f9...8c2d

Error behaviour

Condition	Status	Message
Called with API key instead of OAuth	403	"Key creation requires an OAuth session"
Invalid scope	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."
Workspace slug not found	—	"Workspace not found: <slug>"

Related commands

culvii key list, culvii key rotate, culvii key revoke