app instances

read onlyrepeatable

What is actually running, one row per instance, with the state the platform sees for each. app list and app get report what was configured; this reports what came of it.

A difference between the two numbers is a rollout in progress, a restart, or an instance that cannot be placed.

Usage

outplane app instances [APP]

Arguments

Argument	Type	Description
`APP`	`string`	App name or id. Defaults to the linked app.

Output

Field	Type	Description
`name`	`string`	The instance's own name, which changes on every restart.
`state`	`string`	The platform's reading of the lifecycle, and the field to branch on: pending, starting, running, failing, terminating, terminated. An unrecognised one decodes to unknown:N, carrying the number the server sent. One of `pending`, `starting`, `running`, `failing`, `terminating`, `terminated`, `unknown`.
`phase`	`string`	The runtime's own word, passed through unchanged: Pending, Running, Succeeded, Failed or Unknown. Weaker than state, which separates starting from failing.
`ready`	`bool`	Whether it is taking traffic. Running and not ready is the interesting state during a rollout.
`restarts`	`int`	How many times the container has restarted since the instance was created. The only field that shows a crash loop which has since recovered.
`reason`	`string \| null`	Why it is not up, in one sentence. Null while it is running or still starting.
`createdAt`	`string \| null`	When the instance came into being. The only age an instance that never starts has.
`startedAt`	`string \| null`	When the container running now started. After a restart this, not createdAt, is what "up for" measures from.
`lastExitCode`	`int \| null`	What the previous container exited with, when there was one. The application's own code: 137 is a kill for exceeding the memory limit.
`deploymentId`	`int \| null`	The deployment that put this instance here, so it can be traced to a row in deploy list.
`container`	`string`	The container a shell attaches to.
`container`	`string`
`startedAt`	`string \| null`	RFC 3339, UTC.

Examples

What is running right now

outplane app instances checkout

Find the instance to open a shell on

outplane app instances checkout -o text

Wait for a rollout in a script

outplane app instances --json --fields name,ready

{
  "items": [
    {
      "name": "checkout-7d9f-abcde",
      "ready": true
    },
    {
      "name": "checkout-7d9f-fghij",
      "ready": false
    }
  ],
  "total": 2,
  "truncated": false
}

What to Know

total is what is running, which is not the configured count. app list reports the configuration; a difference between them is a rollout, a restart or a failure to schedule.
phase comes from the container runtime and is passed through unchanged, so a value this release has never seen still arrives intact.
An instance name changes every time it restarts. Do not store one.
state is the field to branch on. phase is the runtime's raw word and cannot tell a container that is starting from one that keeps dying; state can.
createdAt and startedAt answer different questions. The first is how old the instance is, the second is how long the container running now has been up, and after a restart they are hours apart. "Up for" measures from startedAt.
restarts is the only field that shows a crash loop which has since recovered: an instance that restarted ten minutes ago and is running now reads healthy everywhere else.
lastExitCode is the application's own exit code, so it is safe to show a user. 137 means the container was killed for using more memory than it was allowed.
A paused application runs nothing, so this is empty and that is not an error.

Errors

Beyond 0 for success, this command exits with:

Exit	Kind	Meaning
`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.