# 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.1.10/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.                                                               |
| [`kindgi env set`](https://docs.kindgi.com/v0.1.10/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.1.10/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.1.10/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.1.10/reference/cli/env.md#kindgi-env-init)   | Scaffold `.env.example` for a deployment target.                                                                                                                                               |
| [`kindgi env plan`](https://docs.kindgi.com/v0.1.10/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.1.10/deploy/self-hosted/azure-container-apps.md)
- [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md)
- [Set values per environment](https://docs.kindgi.com/v0.1.10/guides/secrets/per-environment-values.md)
- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/secret-manager.md)

### `kindgi env list`

**Synopsis**

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

List resolved env values for the target env (merges config + .env.\<envName>); with --scope, the runtime's values at that scope.

**Options**

| Option            | Default                          | Description                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--env <value>`   | `staging`                        | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`.                                                                                                                                                       |
| `--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) | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`. 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. |

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 env list --env=local
```

**See also**

- [Keep local values in env files](https://docs.kindgi.com/v0.1.10/guides/secrets/env-files.md)
- [`kindgi env`](https://docs.kindgi.com/v0.1.10/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]]
```

Set a KEY=VALUE in .env.\<envName>, or with --scope in the runtime's env values. Refuses to overwrite unless --force.

**Options**

| Option            | Default                    | Description                                                                                                                                                                                                                                                                                   |
| ----------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--env <value>`   | `staging`                  | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`.                                                                                                                                                       |
| `--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>`) | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`. 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. |

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

**Examples**

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

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

From [Give a tool per-project values](https://docs.kindgi.com/v0.1.10/guides/tools/give-a-tool-env-values.md):

```sh
pnpm exec kindgi env set ORDERS_BASE_URL https://orders.example.com --scope=tenant --env=local
```

**See also**

- [Set values per environment](https://docs.kindgi.com/v0.1.10/guides/secrets/per-environment-values.md)
- [Give a tool per-project values](https://docs.kindgi.com/v0.1.10/guides/tools/give-a-tool-env-values.md)
- [`kindgi env`](https://docs.kindgi.com/v0.1.10/reference/cli/env.md#kindgi-env)

### `kindgi env unset`

**Synopsis**

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

Remove KEY from .env.\<envName>, or with --scope from the runtime's env values. Idempotent — no error if the key is absent.

**Options**

| Option            | Default                   | Description                                                                                                                                                                                                                                                                                   |
| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--env <value>`   | `staging`                 | The value set (one environment's values): `local` is the project's own env files, any other name its `.env.<name>`. Default: `staging`.                                                                                                                                                       |
| `--path <value>`  | the current directory     | The pack root, where the env files are. Default: the current directory.                                                                                                                                                                                                                       |
| `--scope <value>` | none (edits `.env.<env>`) | Act on the runtime's env values (`/v1/env`) instead of local files: `tenant`, `org:<orgId>` or `project:<projectId>`. Requires `--env`. 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. |

Every command also takes the [global flags](https://docs.kindgi.com/v0.1.10/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
```

**See also**

- [Deploy on Azure Container Apps](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/azure-container-apps.md)
- [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md)
- [Set values per environment](https://docs.kindgi.com/v0.1.10/guides/secrets/per-environment-values.md)
- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/secret-manager.md)
- [`kindgi env`](https://docs.kindgi.com/v0.1.10/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.1.10/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.1.10/deploy/self-hosted/azure-container-apps.md)
- [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md)
- [Set values per environment](https://docs.kindgi.com/v0.1.10/guides/secrets/per-environment-values.md)
- [Keep secrets in your own secret manager](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/secret-manager.md)
- [`kindgi env`](https://docs.kindgi.com/v0.1.10/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.1.10/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.1.10/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.1.10/deploy/self-hosted/secret-manager.md)
- [`kindgi env`](https://docs.kindgi.com/v0.1.10/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.1.10/reference/cli.md#global-flags).

**Examples**

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

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

From [Deploy on Google Cloud Run](https://docs.kindgi.com/v0.1.10/deploy/self-hosted/cloud-run.md):

```sh
pnpm exec kindgi env plan --env prod > /tmp/pack-env.json
```

**See also**

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