env run

Runs a program on this machine with the application's variables in its environment. It is how to run a migration, a database console or a test suite against the same configuration the deployed application has, without copying a single secret onto disk.

Everything after -- belongs to the program, including its exit code, which becomes this command's own.

Usage

outplane env run <COMMAND...> [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Run a local server against the deployed configuration

outplane env run -- npm start

Run a one-off task against another application

outplane env run --app checkout -- python manage.py migrate

Use shell syntax, by asking for a shell

outplane env run -- sh -c 'echo "$DATABASE_URL" | cut -d@ -f2'

Check which variables a command would get, without running it

outplane env run --dry-run --json -- npm test

{
  "app": "checkout",
  "command": "npm test",
  "keys": [
    "DATABASE_URL",
    "LOG_LEVEL"
  ],
  "variables": 12
}

What to Know

• The exit code is the program's own, whatever it is, so this command's exit code is not from the CLI's table when the program actually ran. A program exiting 2 is not a usage error here.
• A program killed by a signal reports 128 plus the signal number, as a shell does, so an out-of-memory kill is 137 rather than a code that appears nowhere else.
• The program's output is this command's output, unchanged and unbuffered. --json and --fields describe the invocation only, and are not printed at all once the program starts, so nothing of the CLI's lands in the middle of it.
• There is no shell. Arguments are passed to the program exactly as given: no expansion, no globbing, no pipelines. -- sh -c "..." is how to get one.
• This command's own flags go before --. Anything after it belongs to the program, including --json and --app, which is why run -- true --json passes --json to true and produces no structured output.
• A program that is not on PATH is a usage error, exit 2 with env.command_not_found, rather than the 127 a shell would give.
• The application's values overwrite the local ones where the names collide. --pure removes the local environment entirely, which usually means the program cannot find its own interpreter.
• Variables from an assigned group are not included, so the environment here is the application's own variables and not everything the deployed container receives.
• An interrupt reaches the program, and the CLI waits for it to finish rather than returning first.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of env.command_not_found, env.command_not_executable, env.run_failed, usage.missing_argument, context.no_app, app.not_found. Branch on that, or on the exit status. The message is prose and changes.

Related