app shell

Opens a shell inside one running instance, the same session the console opens on its Shell tab. Use it to look at the filesystem, see what a process is doing, or run a one off command against the real thing.

It needs a terminal at both ends, so it is the one command in this group that cannot be scripted or run from a pipeline. Whatever you change inside lives on that single instance until it restarts.

Usage

outplane app shell [APP] [flags]

Arguments

Flags

The global flags apply as well.

Output

Examples

Open a shell on an application

outplane app shell checkout

Open one on a particular instance

outplane app shell checkout --instance checkout-7d9f-abcde

Use bash, on an image that has it

outplane app shell checkout --command bash

Check what a session would open, without opening one

outplane app shell checkout --dry-run --json

{
  "app": "checkout",
  "command": "sh",
  "connected": false,
  "instance": "checkout-7d9f-abcde"
}

What to Know

• This command requires a terminal on both standard input and standard output. Behind a pipe, a redirect or an agent harness it exits 2 with shell.not_interactive and opens nothing. --dry-run is the only form that runs anywhere.
• There is no exit status. The platform attaches a terminal to the session and a terminal reports none, so a command that failed inside the session still ends it with exit 0. Nothing here can be used to decide whether something worked.
• Output is the far end's own bytes, including escape sequences and colour. It is not records, and --json, --fields and --jq do not apply to a live session.
• An instance name changes every time it restarts, so one read a minute ago may already be gone. Without --instance the first ready instance is chosen, and which one that is can differ between two runs a second apart.
• Changes made inside a session live on that one instance until it restarts. They are not configuration, they are not replicated to the other instances, and the next deployment replaces the lot.
• An image with no shell fails the exec, and the reason arrives as text inside the session rather than as an error: by then the socket is open and there is nowhere else to put it.

Errors

Beyond 0 for success, this command exits with:

The code on the error object is one of shell.not_interactive, shell.no_instance, shell.instance_not_found, shell.disconnected, app.not_found, context.no_app. Branch on that, or on the exit status. The message is prose and changes.

Related