Output

The CLI formats for whoever is reading. On a terminal that means text a person can scan. Through a pipe it means JSON, without anyone having to remember a flag.

outplane app list                    # a table
outplane app list | jq '.items[0]'   # JSON, because stdout is not a terminal

Choosing a Format

Write the flag when it matters. A script that runs both on a laptop and in a runner gets a different format in each without one, and --json is one word.

Narrowing the Fields

--fields limits structured output to the fields you name:

outplane app list --json --fields name,status,instances

An unknown name is an error rather than an omission, so a renamed field fails loudly instead of quietly returning nothing.

Lists

A command that returns a list returns one object, not a bare array:

{
  "items": [],
  "total": 0,
  "truncated": false
}

total is what the command could count, and truncated says whether more exists than was returned. Where a command pages, its own page says so.

Streams

Two commands emit NDJSON rather than a document, because a stream with no end cannot be one:

• outplane deploy create --follow while a build runs
• outplane requests --follow as requests arrive

Each line is a complete object, flushed as it arrives, so a reader can act on the first line without waiting for the last.

Commands That Stay Text

Three commands print a bare value in every format, so that command substitution captures the value rather than an object:

DATABASE_URL=$(outplane db url orders)
TOKEN=$(outplane env get API_TOKEN)
ADDRESS=$(outplane port get 3000)

For the same reason, when one of these fails it writes a sentence to standard error and leaves standard output empty, so the variable ends up empty rather than holding an error message. --json still returns the object when that is what is wanted.

outplane logs and outplane deploy logs are text too. A log line has no fields to report, so --json does not change them either.

Which Stream

That split is what makes outplane app list --json > apps.json produce a file that parses, whatever else the command had to say.

--quiet silences everything except errors. It does not change stdout, so a quiet command still writes its data.

Related