# kindgi secrets > Manage per-environment secrets via the /v1/secrets/* wire ## `kindgi secrets` **Synopsis** ```sh signature kindgi secrets ``` Manage per-environment secrets via the /v1/secrets/\* wire. **Commands** | Command | Description | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | [`kindgi secrets list`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-list) | List secret metadata under --scope + --env. | | [`kindgi secrets get`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-get) | Fetch secret metadata (name + version + timestamps only, NEVER the value). | | [`kindgi secrets set`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-set) | Write a new secret value. | | [`kindgi secrets copy`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-copy) | Copy model providers' keys (or the NAMEs given) from your app's env files into Kindgi's own .kindgi/secrets.env, which Kindgi reads first. | | [`kindgi secrets rotate`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-rotate) | Rotate a secret. | | [`kindgi secrets revoke`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-revoke) | Revoke a secret. | | [`kindgi secrets pull`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets-pull) | Fetch secret metadata into .secrets/\/manifest.json. | **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) ### `kindgi secrets list` **Synopsis** ```sh signature kindgi secrets list --env= --scope=[:id] [--include-revoked] [--name-prefix=

] [--cursor=] [--limit=] ``` List secret metadata under --scope + --env. Never returns values. **Options** | Option | Default | Description | | ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--include-revoked` | off | Include revoked secrets, with their `revokedAt` and `revokeReason`. Never a value. | | `--limit ` | `25` (at most `100`) | The most secrets to return (default 25, at most 100). | | `--name-prefix ` | none | Only the secrets whose name starts with this prefix. | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** List the tenant's secrets for the local env. ```sh kindgi secrets list --env=local --scope=tenant ``` Page through the secrets whose names start with ACME\_. ```sh kindgi secrets list --env=production --scope=tenant --name-prefix=ACME_ --limit=10 ``` List revoked secrets too, with when and why each was revoked. ```sh kindgi secrets list --env=production --scope=tenant --include-revoked ``` **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets get` **Synopsis** ```sh signature kindgi secrets get --env= --scope=[:id] ``` Fetch secret metadata (name + version + timestamps only, NEVER the value). **Options** | Option | Default | Description | | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Store a secret](https://docs.kindgi.com/v0.1.10/guides/secrets/store-a-secret.md): ```sh pnpm exec kindgi secrets get RECEIPT_SIGNING_KEY --env=local --scope=tenant ``` **See also** - [Store a secret](https://docs.kindgi.com/v0.1.10/guides/secrets/store-a-secret.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets set` **Synopsis** ```sh signature kindgi secrets set --env= --scope=[:id] [--write-mode=create-new|add-version] [--from-stdin | --from-file ] [--rotation-due-at=] [--if-version=] [--app] ``` Write a new secret value. Default: interactive TTY prompt. Use --from-stdin | --from-file for automation. **Options** | Option | Default | Description | | --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--app` | off | Under `kindgi dev`: write it to your app's env file (the last of `dev.envFiles`, `.env.local` by default) instead of Kindgi's `.kindgi/secrets.env`, for a value your app reads too, such as a webhook signing secret. | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--from-file ` | none (prompts for the value on a terminal) | Read the value from this file instead of prompting. A file group or others can access is refused (`chmod 600`). | | `--from-stdin` | off (prompts for the value on a terminal) | Read the secret's value from stdin instead of prompting. | | `--if-version ` | none | Write only if the secret is still at this version (`0` when it doesn't exist yet); otherwise fail with a conflict. | | `--rotation-due-at ` | none | When the secret is due for rotation: an ISO 8601 time with a zone, or a date (its start, UTC); kept with its metadata. | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | | `--write-mode ` | `create-new` | `create-new` (the default) refuses a secret that exists; `add-version` writes a new version, creating it if needed. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md): ```sh pnpm exec kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant ``` From [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md): ```sh pnpm exec kindgi secrets set OPENAI_API_KEY --env=local --scope=tenant ``` **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets copy` **Synopsis** ```sh signature kindgi secrets copy [NAME…] ``` Copy model providers' keys (or the NAMEs given) from your app's env files into Kindgi's own .kindgi/secrets.env, which Kindgi reads first. Never edits your app's files. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** From [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md): ```sh pnpm exec kindgi secrets copy ``` **See also** - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets rotate` **Synopsis** ```sh signature kindgi secrets rotate --env= --scope=[:id] [--new-value | --from-stdin | --from-file ] [--revoke-old-after=] [--no-wait] ``` Rotate a secret. Async providers polled to terminal; use --no-wait to bypass polling and return wire response. **Options** | Option | Default | Description | | ---------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--from-file ` | none (the secret store rotates the value itself unless `--new-value` or `--from-stdin`) | Read the new value from this file. A file group or others can access is refused (`chmod 600`). | | `--from-stdin` | off | Read the new value from stdin. | | `--new-value` | off | Prompt for the new value (no echo). Without it, `--from-stdin` or `--from-file`, the secret store must rotate the value itself. | | `--no-wait` | off (waits for an asynchronous rotation to finish) | Print the API's first response instead of waiting for an asynchronous rotation to finish. | | `--revoke-old-after ` | none (the old version stays valid) | Revoke the old version this many milliseconds after the rotation (`0`: at once). Without it, the old version stays valid. | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** Rotate a secret, entering the new value at a prompt. ```sh kindgi secrets rotate ACME_WEBHOOK_SECRET --env=production --scope=tenant --new-value ``` Rotate from stdin and revoke the old version after an hour. ```sh kindgi secrets rotate ACME_WEBHOOK_SECRET --env=production --scope=tenant --from-stdin --revoke-old-after=3600000 ``` **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets revoke` **Synopsis** ```sh signature kindgi secrets revoke --env= --scope=[:id] [--hard] [--reason=] ``` Revoke a secret. Default: soft (keeps audit tombstone). --hard: cryptographic erasure. **Options** | Option | Default | Description | | ------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--hard` | off (soft revoke, keeps an audit tombstone) | Erase the value for good instead of keeping an audit tombstone. Cannot be undone. | | `--reason ` | none | Why the secret is revoked; kept on the record as `revokeReason`. | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** Revoke a secret, keeping an audit tombstone. ```sh kindgi secrets revoke ACME_WEBHOOK_SECRET --env=production --scope=tenant --reason="rotated after a leak" ``` Erase a secret's value for good. ```sh kindgi secrets revoke ACME_OLD_KEY --env=production --scope=tenant --hard ``` **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets) ### `kindgi secrets pull` **Synopsis** ```sh signature kindgi secrets pull --env= --scope=[:id] [--path

] ``` Fetch secret metadata into .secrets/\/manifest.json. Never fetches bytes. **Options** | Option | Default | Description | | ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--env ` | required | The environment the secret belongs to. Required, unless the runtime keeps its values under one env: then that one, and a set or rotation under another is refused. There, it may also name one of the pack's `environments` with a `project`: the secret is that project's, under the env the runtime serves, so --scope is left out. Under `kindgi dev`, `local` is the pack's env files. | | `--path ` | the current directory | The pack directory to write `.secrets//manifest.json` under (default: the current directory). | | `--scope ` | required | Where the secret lives: `tenant`, `org:` or `project:`. Required, unless --env names one of the pack's environments with a project. | Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/reference/cli.md#global-flags). **Examples** Write the tenant's secret metadata to .secrets/production/manifest.json. ```sh kindgi secrets pull --env=production --scope=tenant ``` Write the manifest under another pack directory. ```sh kindgi secrets pull --env=staging --scope=project: --path=./acme-ops ``` **See also** - [Connect Anthropic](https://docs.kindgi.com/v0.1.10/guides/models/anthropic.md) - [Connect OpenAI, Gemini, Groq or OpenRouter](https://docs.kindgi.com/v0.1.10/guides/models/api-key-presets.md) - [Models](https://docs.kindgi.com/v0.1.10/guides/models.md) - [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md) - [`kindgi secrets`](https://docs.kindgi.com/v0.1.10/reference/cli/secrets.md#kindgi-secrets)