env set

Adds variables, or replaces the ones that already exist. Only the keys you name are touched, so nothing you did not mention can be lost.

Saving is not deploying. Without --deploy the running application keeps the values it started with, and this is the easiest thing here to get wrong.

--hangar <name> sets them on a Hangar instead, which picks them up the next time it starts. --restart restarts it in the same command, ending whatever runs in its terminal.

Usage

outplane env set <ASSIGNMENT...> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Set one variable on the linked app

outplane env set LOG_LEVEL=debug

Set several and apply them at once

outplane env set LOG_LEVEL=debug TIMEOUT=30 --app checkout --deploy

See what would happen

outplane env set LOG_LEVEL=debug --dry-run

Give an application a managed database's connection string

outplane env set DATABASE_URL="$(outplane db url orders)" --app checkout --deploy

Set one and read what changed

outplane env set LOG_LEVEL=debug --json --fields keys,changed

{
  "changed": true,
  "keys": [
    "LOG_LEVEL"
  ]
}

Set one on a Hangar and restart it to apply it now

outplane env set LOG_LEVEL=debug --hangar myhangar --restart --json --fields app,changed,restarted

{
  "app": "myhangar",
  "changed": true,
  "restarted": true
}

What to Know

• Saving does not restart anything. Without --deploy the running application keeps the values it started with, which is the single easiest thing to get wrong here.
• Only the named keys are changed. This command never sends the whole set, so it cannot drop a variable it was not told about.
• A value may contain an equals sign: only the first one separates the key, so KEY=a=b sets KEY to a=b.
• HOSTNAME and any key starting with OP_, KUBERNETES_ or HANGAR_ are refused. PORT is not reserved and may be set.
• Setting an existing key replaces it, so running this twice with the same arguments leaves the same state.
• deploymentId is null unless --deploy was given. A queued deployment is not a finished one; follow it with outplane deploy logs.
• --hangar names a Hangar instead of an application, and is refused together with --app. A Hangar is an application record with the same id, so the requests are the same, and a result's app field holds the Hangar's name.
• Saving changes nothing running in a Hangar either. It is started from its saved variables, groups and ports, so without --restart a change applies at its next outplane hangar restart, or at outplane hangar resume when it is paused. --restart is refused without --hangar, and --deploy with it.
• --restart stops everything running in the Hangar's terminal, agents included, and disconnects anyone connected; files under /home/hangar stay. An agent working inside the Hangar ends its own session by passing it. On a paused Hangar it restarts nothing and does not fail, and a restart the server refuses still exits 0 once the change is saved, with restarted false and the reason on stderr.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of usage.bad_assignment, usage.duplicate_key, env.reserved_key, env.reserved_prefix, env.key_too_long, env.value_too_long, env.too_many, context.no_app, app.not_found, hangar.not_found, hangar.ambiguous, usage.conflicting_flags, usage.empty_argument. Branch on that, or on the exit status. The message is prose and changes.

Related