Skip to main content
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 describes the file location, the limits, the placeholders, and the error codes.

​
Commands

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.
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}}.

​
orbit env:update

Add or replace one stored value.
Quote the value for your shell, so Orbit receives the string you mean.
{{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.
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.
env.sync_unconfirmed means that the Gateway cannot confirm the write. Run the command again to check the file.
  • instance:database:add writes database keys into the same stored configuration.
  • instance:deploy synchronizes the stored configuration before it runs deploy steps.
  • doctor reports when a production .env differs from the stored configuration.