env push

writesrepeatable--dry-run

Sends a .env file to the application, skipping the keys whose value already matches.

It is not a synchronisation. A variable set on the application and missing from the file is left exactly where it is. Removing one is env unset.

Usage

outplane env push [FILE] [flags]

Arguments

Argument	Type	Description
`FILE`	`string`	Path to the file. Defaults to .env.

Flag	Type	Description
`--app`	`string`	Application name or id. Defaults to the linked app. A flag rather than an argument, so that variable names cannot be mistaken for it.
`--deploy`	`bool`	Deploy afterwards, so the change reaches the running app.

Output

Field	Type	Description
`action`	`string`	One of `push`.
`file`	`string`	The path that was read.
`app`	`string`
`appId`	`string`
`added`	`int`	Keys the application did not have.
`changed`	`int`	Keys whose value differed.
`unchanged`	`int`	Keys that were already identical, and were not sent.
`addedKeys`	`array`
`changedKeys`	`array`
`unchangedKeys`	`array`
`sent`	`bool`	False for a dry run, and false when nothing differed.
`deploymentId`	`int \| null`	The deployment --deploy started, or null when it was not given.

Examples

See what a file would change, without changing it

outplane env push --dry-run

{
  "action": "push",
  "added": 2,
  "addedKeys": [
    "CACHE_URL",
    "LOG_LEVEL"
  ],
  "changed": 1,
  "changedKeys": [
    "TIMEOUT"
  ],
  "file": ".env",
  "sent": false,
  "unchanged": 9
}

Apply it

outplane env push

Apply a named file to a named application, and deploy

outplane env push .env.production --app checkout --deploy

Read the result in a pipeline

outplane env push --json --fields added,changed,sent

What to Know

This is not a synchronisation. A key set on the application and missing from the file is left alone; nothing here removes anything. outplane env unset removes, by name.
Only keys that are new or whose value differs are sent. sent is false when every key already matched, and that is a success, not a failure. A file with no variables in it is the same case: nothing is sent, nothing is removed, and the exit code is 0.
Keys are compared the way the server compares them, ignoring case, so a file with path= changes an existing PATH rather than adding a second variable.
Saving does not restart anything. Without --deploy the running application keeps the values it started with.
The whole file is validated before anything is sent: a reserved name or an over-long value fails naming the line, and no part of the file is applied.
An unquoted # is part of the value, not the start of a comment. A password ending in #1 survives a round trip; a trailing comment does not work.
deploymentId is null unless --deploy was given. A queued deployment is not a finished one; follow it with outplane deploy logs.

Errors

Beyond 0 for success, this command exits with:

Exit	Kind	Meaning
`1`	`internal`	An unexpected failure in the CLI itself.
`2`	`usage`	Invalid arguments, unknown flag, or client-side validation failure.
`3`	`auth`	Not authenticated, token revoked or expired, or forbidden for this team.
`5`	`not_found`	The named resource does not exist, or is not visible to this credential.
`8`	`upstream`	The Out Plane API returned a server error.

The code on the error object is one of env.file_not_found, env.file_invalid, env.file_unreadable, env.reserved_key, env.reserved_prefix, env.key_too_long, env.value_too_long, env.too_many, context.no_app, app.not_found. Branch on that, or on the exit status. The message is prose and changes.