> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ironrun env — Manage Encrypted Named Environments

> ironrun env subcommands create, switch, clone, import, and manage named secret environments in the encrypted local vault. Values are never revealed.

The `env` subcommand gives you granular control over named environments in the encrypted vault. Every environment is a named collection of secrets — stored outside your repository, encrypted at rest with a rotating data key wrapped by a project root key in the native OS credential manager. ironrun never offers reveal, clipboard-copy, or plaintext export.

## Top-level shortcut commands

For the most common operations, ironrun provides short top-level aliases so you don't need to type `env` every time:

| Shortcut                 | Equivalent                              | Description                                                    |
| ------------------------ | --------------------------------------- | -------------------------------------------------------------- |
| `ironrun new <name>`     | `ironrun env create <name>`             | Create and switch to a new persistent environment              |
| `ironrun session [name]` | `ironrun env create <name> --temporary` | Create and switch to a temporary environment (default TTL 24h) |
| `ironrun use <name>`     | `ironrun env use <name>`                | Switch the active environment                                  |
| `ironrun envs`           | `ironrun env list`                      | List environment names and key names                           |

## Subcommands

| Subcommand                       | Description                                                      |
| -------------------------------- | ---------------------------------------------------------------- |
| `env init <name>`                | Register this project and create its first environment set       |
| `env set [<name>] <KEY>`         | Add or update a secret via a masked prompt                       |
| `env create <name>`              | Create a new environment (`new` is an alias)                     |
| `env clone <src> <dst>`          | Copy all entries from one environment to another                 |
| `env use <name>`                 | Switch the active environment (`switch` is an alias)             |
| `env list`                       | List environments and key names, never values (`ls` is an alias) |
| `env status [<name>]`            | Value-blind summary of configured keys and policy coverage       |
| `env rotate <name> <KEY>`        | Replace one value using a masked prompt                          |
| `env delete <name> <KEY>`        | Delete a single key after confirmation                           |
| `env remove <name>`              | Remove an entire environment set after confirmation              |
| `env file [<name>] <KEY> <path>` | Encrypt one owner-only file secret                               |
| `env import <name> <path>`       | Import from an owner-only `.env` file                            |
| `env export <name> <path>`       | Write a `KEY=` template only — no values                         |
| `env prune`                      | Delete expired temporary environments                            |
| `env doctor`                     | Validate project identity, storage, expiry, and policy coverage  |

## Common workflows

### Add a secret to the active environment

```bash theme={null}
ironrun env set DATABASE_URL
# Masked prompt — the value is never echoed to the terminal
```

If you want to target a specific environment rather than the active one, pass its name first:

```bash theme={null}
ironrun env set staging DATABASE_URL
```

### Create a staging environment and populate it from dev

```bash theme={null}
ironrun env create staging
ironrun env clone dev staging
ironrun env use staging
```

### Import from a `.env` file

```bash theme={null}
ironrun env import dev .env
# Shows key names only, asks for confirmation, then encrypts and verifies
```

`env import` only accepts owner-only files (permission mode `600`). It refuses files inside the project directory unless you pass `--allow-project-file`, and it refuses any file readable by group or other.

## Temporary environments

Temporary environments expire automatically. This is useful for short-lived work, CI overrides, or agent sessions you want to clean up without manual intervention:

```bash theme={null}
ironrun env create session --temporary --ttl 8h
ironrun env use session
# ... work ...
ironrun env prune   # removes all expired sets
```

The default TTL for temporary environments is 24 hours. The `--ttl` flag accepts standard Go duration strings: `30m`, `8h`, `24h`.

## One-run environment override

You don't have to switch environments just to run a single command against a different set. Use `--set` on `ironrun run`:

```bash theme={null}
ironrun run --set staging deploy
```

The active environment for your project is unchanged after this invocation.

## Flags

### `env set`

<ParamField query="--from-stdin" type="boolean" default="false">
  Read the secret value from stdin instead of a masked prompt. Requires `--unsafe`.
</ParamField>

<ParamField query="--unsafe" type="boolean" default="false">
  Acknowledge that piped input may appear in process listings or shell history. Required when using `--from-stdin`.
</ParamField>

### `env create`

<ParamField query="--temporary" type="boolean" default="false">
  Mark this environment as temporary so it is eligible for automatic expiry.
</ParamField>

<ParamField query="--ttl" type="duration" default="24h">
  Lifetime for a temporary environment. Accepts Go duration strings such as `8h` or `30m`.
</ParamField>

### `env clone`

<ParamField query="--yes" type="boolean" default="false">
  Skip the confirmation prompt before cloning secret values.
</ParamField>

### `env remove`

<ParamField query="--yes" type="boolean" default="false">
  Skip the confirmation prompt before removing the entire environment set.
</ParamField>

### `env import`

<ParamField query="--allow-project-file" type="boolean" default="false">
  Allow importing a `.env` file that lives inside the project directory. The file must still have owner-only permissions (`600`).
</ParamField>

<Warning>
  `env export` writes only `KEY=` template lines. It never exports plaintext secret values. There is no flag or option that changes this behaviour — ironrun does not have a plaintext export path.
</Warning>

<Note>
  The encrypted vault lives at `~/.ironrun/vaults/`, outside your repository. Project metadata lives under `.ironrun/` in your project directory and contains no secret values. The `.ironrun/` directory is automatically git-ignored on creation.
</Note>