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

# env

> Import, update, and synchronize the Gateway-owned environment configuration of one Instance.

The Gateway stores the environment configuration of every Instance as encrypted keys and values. The `env` family imports an existing `.env`, changes one stored value, and writes the complete stored configuration back into the Instance's `.env`.

[Instance environment variables](/docs/reference/environment-variables) describes the file location, the limits, the placeholders, and the error codes.

## Commands

| Command | Result |
| - | - |
| [`env:import`](#orbit-envimport) | Import the Instance's `.env` into stored configuration. |
| [`env:update`](#orbit-envupdate) | Add or replace one stored value. |
| [`env:sync`](#orbit-envsync) | Replace the Instance's `.env` with the complete stored configuration. |

Every command takes `--instance=SELECTOR`: a positive Instance ID or the exact domain of its Route. The Instance must have exactly one Route; otherwise the Gateway returns `env.owner_unavailable`. Every command accepts `--json`. Output holds the Instance ID, the operation, whether something changed, the total stored key count, and the request ID. Values never appear. Import and update change stored configuration only; the file stays the same until you run `env:sync`.

## orbit env:import

Import the Instance's `.env` into stored configuration. The Gateway never reads `.env.example`.

```bash theme={"dark"}
orbit env:import --instance=SELECTOR [--replace] [--json]
```

| Option | Meaning |
| - | - |
| `--replace` | Replace stored keys that the file also holds. Stored keys that the file lacks stay. |

Without `--replace`, a file key that is already stored returns `env.import_conflict`, and nothing is stored. For a Laravel Instance, import stores `APP_URL` as `https://{{instance.domain}}`.

```bash theme={"dark"}
orbit env:import --instance=12
orbit env:import --instance=shop.example.test --replace
```

## orbit env:update

Add or replace one stored value.

```bash theme={"dark"}
orbit env:update --instance=SELECTOR --key=KEY --value=VALUE [--json]
```

| Option | Meaning |
| - | - |
| `--key=KEY` | 1 to 255 characters that start with a letter or underscore. |
| `--value=VALUE` | The exact string, at most 65,536 bytes. |

Quote the value for your shell, so Orbit receives the string you mean.

| Value | Write it as |
| - | - |
| Empty | `--value=''` |
| Text with spaces or shell characters | `--value='hello world $1'` |
| A placeholder | `--value='https://{{instance.domain}}'` |
| `false` or `0` | `--value=false` stores the string `false`. |

```bash theme={"dark"}
orbit env:update --instance=12 --key=MAIL_MAILER --value=log
orbit env:update --instance=12 --key=APP_URL --value='https://{{instance.domain}}'
```

`{{instance.domain}}` resolves to the Route domain, and `{{instance.environment}}` to `development` on `app-dev` or `production` on `app-prod`, when the Gateway renders the file. Any other placeholder returns `env.configuration_invalid` with the key and the rule.

## orbit env:sync

Replace the Instance's `.env` with the complete stored configuration. Edits to stored keys disappear. A key that exists only in the file stops the sync with `env.sync_would_drop_keys`, unless Orbit wrote or detached that key itself. To keep such keys, store them with `env:update`, or run `env:import` (with `--replace` when the file's other keys are already stored). Otherwise remove them from the file.

```bash theme={"dark"}
orbit env:sync --instance=SELECTOR [--json]
```

```bash theme={"dark"}
orbit env:sync --instance=12
```

<Note>
  Synchronization changes only the file. It does not clear a framework cache or restart a Process. Run those steps afterwards when running code must see the new values.
</Note>

`env.sync_unconfirmed` means that the Gateway cannot confirm the write. Run the command again to check the file.

## Related

* [`instance:database:add`](/docs/cli/instance#orbit-instancedatabaseadd) writes database keys into the same stored configuration.
* [`instance:deploy`](/docs/cli/instance#orbit-instancedeploy) synchronizes the stored configuration before it runs deploy steps.
* [`doctor`](/docs/cli/doctor) reports when a production `.env` differs from the stored configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.