Repository navigation
CLI Output Modes
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.
| 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 is used only in the human layout on a terminal. It is switched off when:
-
NO_COLORis set to any non-empty value (the no-color.org convention); -
TERMisdumb; - 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 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.
| 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.
Stack desktop client + CLI wiki — condensed from the repo docs. App repo: https://github.com/escacs/stack-app. CLI repo (private): https://github.com/escacs/stack.