Skip to content

CLI Output Modes

Mel edited this page Nov 10, 2026 · 1 revision

Every command prints one of three forms.

Mode Chosen by Use it for
human --human, or stdout is a terminal (the default there) reading: aligned columns, colour on a terminal, hints
plain --plain, or stdout is not a terminal (the default when piped) scripts and agents: one line per entry, plain text
json --json scripts that need fields: one JSON object on stdout

Precedence, highest first: --json, then --plain, then --human or the terminal default. So --json --human prints JSON, and --human --plain on a terminal prints plain text.

Script against plain output or --json. Plain output is one line per entry or step, with no alignment and no cutting. --json is the structured form. The human layout (column widths, truncation, hints) is for reading and can change.

Flags that change output

Flag Applies to Effect
--human list, search, show, status, init, import, update, remove, sync, preset apply force the aligned layout (no colour when piped)
--plain the same commands force plain text, even on a terminal
--json list, search, show, status, init, import, update, remove, sync, preset, remote one JSON object on stdout
--full list, search human layout only: wrap long summaries instead of cutting them. Plain output is never cut
--manifest show human layout only: append the raw stack.json. Plain show always includes the manifest
--verbose list, search, show, path, import show raw git errors for remote libraries (see CLI Remote Libraries)

The human layout fits the terminal width, clamped to 60 to 160 columns (100 when the width is unknown). Long summaries are cut with … unless --full is given.

Colour

Colour is used only in the human layout on a terminal. It is switched off when:

  • NO_COLOR is set to any non-empty value (the no-color.org convention);
  • TERM is dumb;
  • stdout is not a terminal, or the output is plain or JSON.

Checked on a pseudo-terminal: the default prints escape codes; NO_COLOR=1 and TERM=dumb print none; --plain prints none.

Errors and stderr

Errors always go to stderr as plain text, with exit code 1, even when --json was given. So stdout stays parseable JSON when a command fails. Notes and warnings about remote libraries also go to stderr.

Exit codes

Code Meaning
0 The command ran. This includes a --dry-run that reports conflicts, an update that wrote conflict markers, and remote status with a library in error
1 Any error the CLI throws (usage, unknown entry, refusal, git failure), remote sync when a library failed, and catalog or check when they find problems

No other codes are used. Exit 0 does not mean "no conflicts": check the CONFLICT lines, or the conflicts array in --json, after a dry run or an update.

See also: CLI Discover, CLI Recipes, CLI Errors and Hints.

Clone this wiki locally