# kindgi env

> The values in one environment — a value set: the pack's local env files, and with --scope the runtime's (a tool's `ctx.env`, per project, org or tenant)

## `kindgi env`

**Synopsis**

```sh signature
kindgi env <command>
```

The values in one environment — a value set: the pack's local env files, and with --scope the runtime's (a tool's `ctx.env`, per project, org or tenant). For the order projects go live through, see `kindgi environments`.

**Commands**

| Command                                                                                    | Description                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`kindgi env list`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-list)   | List resolved env values for the target env (merges config + .env.\<envName>); with --scope, the runtime's values at that scope, and the names set to a cloud secret there.                    |
| [`kindgi env set`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-set)     | Set a KEY=VALUE in .env.\<envName>, or with --scope in the runtime's env values.                                                                                                               |
| [`kindgi env unset`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-unset) | Remove KEY from .env.\<envName>, or with --scope from the runtime's env values.                                                                                                                |
| [`kindgi env pull`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-pull)   | Fetch remote env values via /v1/env/\* and merge into .env.\<envName>.                                                                                                                         |
| [`kindgi env init`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-init)   | Scaffold `.env.example` for a deployment target.                                                                                                                                               |
| [`kindgi env plan`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env-plan)   | Show the process env a deployed pack service gets in --env: each name the pack declares (env.required / env.optional) and its value or Secret Manager reference from environments.\<name>.env. |

**See also**

- [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/azure-container-apps.md)
- [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md)
- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/secret-manager.md)
- [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md)

### `kindgi env list`

**Synopsis**

```sh signature
kindgi env list [--env <name>] [--reveal] [--force-reveal] [--path <dir>] [--scope=<kind>[:id]]
       kindgi env list --cloud-secret --tenant=<tenantId> --scope=<kind>[:id] --env=<name>
```

List resolved env values for the target env (merges config + .env.\<envName>); with --scope, the runtime's values at that scope, and the names set to a cloud secret there. As the operator, --cloud-secret lists those with each one's path, for the tenant --tenant names.

**Options**

| Option             | Default                                                          | Description                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--cloud-secret`   | off                                                              | List the names set to a cloud secret, each with its path, at --scope of the tenant --tenant names and under --env. Operators only: a system key holding `system:env-refs`.                                                                                                                                                           |
| `--env <value>`    | `staging`; required with `--cloud-secret`                        | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`; required with `--cloud-secret`, which names the env the runtime serves.                                                                                                                      |
| `--force-reveal`   | off                                                              | With `--reveal`, print the values even when stdout isn't a terminal (a file, a pipe, CI).                                                                                                                                                                                                                                            |
| `--path <value>`   | the current directory                                            | The pack root, where the env files are. Default: the current directory.                                                                                                                                                                                                                                                              |
| `--reveal`         | off                                                              | Print the values instead of redacting them. Refused when stdout isn't a terminal (a file, a pipe), unless `--force-reveal` is also given.                                                                                                                                                                                            |
| `--scope <value>`  | none (reads the local env files); required with `--cloud-secret` | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`, and is required with `--cloud-secret`. On a runtime that keeps its values under one env, `--scope=project` with `--env` naming one of the pack's environments is that environment's project. |
| `--tenant <value>` | none: required with `--cloud-secret`                             | With `--cloud-secret`: the tenant whose env it is, acted on as the operator. The token (`KINDGI_API_TOKEN`) is then a system key holding `system:env-refs`.                                                                                                                                                                          |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

From [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md):

```sh
npx --yes @kindgi/cli@0.4 env list --cloud-secret \
```

From [Keep local values in env files](https://docs.kindgi.com/v0.4.0/guides/secrets/env-files.md):

```sh
pnpm exec kindgi env list --env=local
```

**See also**

- [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md)
- [Keep local values in env files](https://docs.kindgi.com/v0.4.0/guides/secrets/env-files.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)

### `kindgi env set`

**Synopsis**

```sh signature
kindgi env set <KEY> <VALUE> [--env <name>] [--force] [--path <dir>] [--scope=<kind>[:id]]
       kindgi env set <KEY> --cloud-secret <projects/<p>/secrets/<s>/versions/<n>> --tenant=<tenantId> --scope=<kind>[:id] --env=<name> [--force]
```

Set a KEY=VALUE in .env.\<envName>, or with --scope in the runtime's env values. Refuses to overwrite unless --force. As the operator, --cloud-secret sets KEY to a version of a secret your cloud holds, for the tenant --tenant names.

**Options**

| Option                   | Default                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cloud-secret <value>` | none: sets a value                                         | Set KEY, at --scope of the tenant --tenant names and under --env, to this version of a secret your cloud holds: `projects/<project>/secrets/<secret>/versions/<number>`, a number, never `latest`. A pack service that declares KEY is given it by that name, and reads the value from your cloud as the pack service's own account, which must be able to read it. Kindgi keeps the name, never the value. Takes no VALUE. Operators only: a system key holding `system:env-refs`. |
| `--env <value>`          | `staging`; required with `--cloud-secret`                  | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`; required with `--cloud-secret`, which names the env the runtime serves.                                                                                                                                                                                                                                                                     |
| `--force`                | off                                                        | Change a key an env file (or, with `--scope`, that scope) already sets: overwrite it, or override a lower-precedence file. By default `set` refuses. With `--scope`, it also sets a value already there again, as a new revision.                                                                                                                                                                                                                                                   |
| `--path <value>`         | the current directory                                      | The pack root, where the env files are. Default: the current directory.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `--scope <value>`        | none (writes `.env.<env>`); required with `--cloud-secret` | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`, and is required with `--cloud-secret`. On a runtime that keeps its values under one env, `--scope=project` with `--env` naming one of the pack's environments is that environment's project.                                                                                                                                                |
| `--tenant <value>`       | none: required with `--cloud-secret`                       | With `--cloud-secret`: the tenant whose env it is, acted on as the operator. The token (`KINDGI_API_TOKEN`) is then a system key holding `system:env-refs`.                                                                                                                                                                                                                                                                                                                         |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

From [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md):

```sh
npx --yes @kindgi/cli@0.4 env set STRIPE_KEY \
```

From [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md):

```sh
pnpm exec kindgi env set ORDERS_API_URL https://orders.staging.example.com --env=staging
```

**See also**

- [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md)
- [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md)
- [Give a tool per-project values](https://docs.kindgi.com/v0.4.0/guides/tools/give-a-tool-env-values.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)

### `kindgi env unset`

**Synopsis**

```sh signature
kindgi env unset <KEY> [--env <name>] [--path <dir>] [--scope=<kind>[:id]]
       kindgi env unset <KEY> --cloud-secret --tenant=<tenantId> --scope=<kind>[:id] --env=<name>
```

Remove KEY from .env.\<envName>, or with --scope from the runtime's env values. Idempotent — no error if the key is absent. As the operator, --cloud-secret removes the cloud secret KEY is set to, for the tenant --tenant names.

**Options**

| Option             | Default                                                   | Description                                                                                                                                                                                                                                                                                                                          |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--cloud-secret`   | off                                                       | Remove the cloud secret KEY is set to, at --scope of the tenant --tenant names and under --env: its pack services lose it at their next revision. Operators only: a system key holding `system:env-refs`.                                                                                                                            |
| `--env <value>`    | `staging`; required with `--cloud-secret`                 | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`; required with `--cloud-secret`, which names the env the runtime serves.                                                                                                                      |
| `--path <value>`   | the current directory                                     | The pack root, where the env files are. Default: the current directory.                                                                                                                                                                                                                                                              |
| `--scope <value>`  | none (edits `.env.<env>`); required with `--cloud-secret` | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`, and is required with `--cloud-secret`. On a runtime that keeps its values under one env, `--scope=project` with `--env` naming one of the pack's environments is that environment's project. |
| `--tenant <value>` | none: required with `--cloud-secret`                      | With `--cloud-secret`: the tenant whose env it is, acted on as the operator. The token (`KINDGI_API_TOKEN`) is then a system key holding `system:env-refs`.                                                                                                                                                                          |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Remove a key from the staging env file.

```sh
kindgi env unset ORDERS_API_URL --env=staging
```

Remove a key from the runtime's tenant-wide values.

```sh
kindgi env unset ORDERS_REGION --scope=tenant --env=local
```

From [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md):

```sh
npx --yes @kindgi/cli@0.4 env unset STRIPE_KEY --cloud-secret \
```

**See also**

- [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)

### `kindgi env pull`

**Synopsis**

```sh signature
kindgi env pull [--env <name>] --scope=<kind>[:id] [--path <dir>] [--overwrite-existing]
```

Fetch remote env values via /v1/env/\* and merge into .env.\<envName>. Requires --scope, unless --env names one of the pack's environments with a project, on a runtime that keeps its values under one env.

**Options**

| Option                 | Default               | Description                                                                                                                                                                                                                                                                       |
| ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--env <value>`        | `staging`             | The environment to pull, written to its `.env.<name>` (`local`: the project's own env files). Default: `staging`, or the env the runtime keeps its values under when it keeps them under one.                                                                                     |
| `--overwrite-existing` | off                   | Replace keys an env file already sets. By default they are skipped.                                                                                                                                                                                                               |
| `--path <value>`       | the current directory | The pack root, where the env files are. Default: the current directory.                                                                                                                                                                                                           |
| `--scope <value>`      | required              | Whose values to pull: `tenant`, `org:<orgId>` or `project:<projectId>`. Required. On a runtime that keeps its values under one env, `--env` naming one of the pack's environments pulls its project's values into its `.env.<name>`, with `--scope=project` or with no `--scope`. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Pull a project's env values into .env.staging, skipping keys already set.

```sh
kindgi env pull --env=staging --scope=project:<project-id>
```

Pull the tenant's values and replace keys the file already sets.

```sh
kindgi env pull --env=staging --scope=tenant --overwrite-existing
```

**See also**

- [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/azure-container-apps.md)
- [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md)
- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/secret-manager.md)
- [Serve many tenants](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/serve-many-tenants.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)

### `kindgi env init`

**Synopsis**

```sh signature
kindgi env init [--secrets-backend=<none|postgres|secret-manager>] [--kms=<gcp|azure|aws|libsodium|vault>] [--secrets-manager=<azure|gcp|aws|vault>] [--out=<path>] [--force] [--non-interactive]
```

Scaffold `.env.example` for a deployment target. Interactive prompt when flags omit an axis and stdin is a TTY.

**Options**

| Option                      | Default                                                                                      | Description                                                                                                               |
| --------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--force`                   | off                                                                                          | Overwrite an existing file at the output path. By default `init` refuses.                                                 |
| `--kms <value>`             | none (asked for when the postgres backend needs it; an error with `--non-interactive`)       | The KMS for the `postgres` backend: `gcp`, `azure`, `aws`, `libsodium` or `vault`. Asked for when needed and omitted.     |
| `--non-interactive`         | off (prompts when stdin is a terminal)                                                       | Never prompt: fail when `--secrets-backend`, or a needed `--kms` or `--secrets-manager`, is missing.                      |
| `--out <value>`             | `.env.example` in the current directory                                                      | Where to write the file. Default: `.env.example` in the current directory.                                                |
| `--secrets-backend <value>` | required (asked for on a terminal)                                                           | The deployment's secrets backend: `none`, `postgres` or `secret-manager`. Asked for when omitted on a terminal.           |
| `--secrets-manager <value>` | none (asked for when the secret-manager backend needs it; an error with `--non-interactive`) | The secret manager for the `secret-manager` backend: `azure`, `gcp`, `aws` or `vault`. Asked for when needed and omitted. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

Scaffold .env.example for a Postgres backend with Google Cloud KMS.

```sh
kindgi env init --secrets-backend=postgres --kms=gcp --non-interactive
```

Scaffold it for a cloud secret manager, writing to a chosen file.

```sh
kindgi env init --secrets-backend=secret-manager --secrets-manager=gcp --out=.env.production.example
```

From [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/secret-manager.md):

```sh
pnpm exec kindgi env init --secrets-backend=secret-manager --secrets-manager=aws
```

**See also**

- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/secret-manager.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)

### `kindgi env plan`

**Synopsis**

```sh signature
kindgi env plan [--env <name>] [--format=terraform|gcloud] [--path <dir>]
```

Show the process env a deployed pack service gets in --env: each name the pack declares (env.required / env.optional) and its value or Secret Manager reference from environments.\<name>.env. Prints Terraform input (default) or gcloud flags; exits 1 when a required name has no value or a secret is given in the clear.

**Options**

| Option             | Default               | Description                                                                                                                                                                                                  |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--env <value>`    | `staging`             | The environment to plan, from `environments.<name>.env` in `kindgi.config.ts`. Default: `staging`.                                                                                                           |
| `--format <value>` | `terraform`           | The output: `terraform` (default) for Terraform input, or `gcloud` for `--update-env-vars` / `--update-secrets` flags (they add or replace the listed names, and leave the service's other variables alone). |
| `--path <value>`   | the current directory | The pack root, where `kindgi.config.ts` is. Default: the current directory.                                                                                                                                  |

Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags).

**Examples**

From [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/azure-container-apps.md):

```sh
pnpm exec kindgi env plan --env dev > pack-env.json
```

From [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md):

```sh
pnpm exec kindgi env plan --env=staging
```

**See also**

- [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.4.0/deploy/self-hosted/azure-container-apps.md)
- [Set values per environment](https://docs.kindgi.com/v0.4.0/guides/secrets/per-environment-values.md)
- [`kindgi env`](https://docs.kindgi.com/v0.4.0/reference/cli/env.md#kindgi-env)