Output Formats & Exit Codes
JSON by default, table and YAML formats, global flags, the structured error envelope, and the exit-code contract.
On this page9
The CLI is designed to be parsed by machines first and read by humans second. This page documents the output contract — formats, global flags, the error envelope, and exit codes — that holds across every command.
Output is JSON by default
Unless you ask otherwise, commands print compact JSON. Lists come back as bare JSON arrays:
trickest space ls[{"name":"Solutions","id":"5c57db3d-…","description":"…","created":"2025-12-29T16:10:55Z"}, …]Pipe to jq for everything:
trickest space ls | jq -r '.[].name'
trickest run get <id> | jq '.nodes[] | select(.status != "SUCCEEDED")'Global flags
Global flags are parsed by the root command, so place them before the subcommand:
trickest --output table node ls # correct| Flag | Effect |
|---|---|
--output <json|table|yaml> | Output format. Default json. |
--quiet | Suppress human status lines, leaving only machine output. |
--verbose | Extra diagnostic logging. |
--no-color | Disable ANSI color. |
--absolute | ISO-8601 timestamps instead of relative ("2h ago"). |
--bytes | Exact byte sizes instead of pretty sizes ("290.6KB"). |
--dry-run | For mutating commands: show what would change without applying it. |
-V, --version | Print the CLI version. |
-h, --help | Show help at any level. |
Format examples
Table (human-friendly):
trickest --output table space ls┌──────────────────┬──────────────────────────────────────┬─────────────────────────────┐
│ Name │ ID │ Created │
├──────────────────┼──────────────────────────────────────┼─────────────────────────────┤
│ Solutions │ 5c57db3d-1bea-4155-a474-30e397889642 │ 2025-12-29T16:10:55.856630Z │
└──────────────────┴──────────────────────────────────────┴─────────────────────────────┘YAML:
trickest --output yaml space ls- name: Solutions
id: 5c57db3d-1bea-4155-a474-30e397889642
description: ""
created: 2025-12-29T16:10:55.856630ZOutput-shape caveats
Most ls commands return a bare array, but a few differ — know these before you
write a jq filter:
The error envelope
Every handled error is the same JSON object:
{"code":"ERR_NOT_FOUND","message":"…human-readable, often with the fix…","hint":"…or null…"}The message is unusually actionable — it frequently names the exact remediation
(e.g. "use workflow get <id> and read schedule_info"). Read it before
retrying.
Exit codes
Branch on these in scripts. They are stable and distinct per error class:
| Exit | Code(s) | Meaning | Example trigger |
|---|---|---|---|
0 | — | Success | trickest space ls |
1 | ERR_API, ERR_UNEXPECTED | Backend/HTTP error, or a backend-gated feature | sandbox status → HTTP 405 |
1 | (usage) | Missing argument or unknown command | trickest workflow info (no id) |
2 | ERR_AUTH | Authentication rejected | Invalid/missing token |
3 | ERR_NOT_FOUND | Resource or context not found | Stale context.workflow |
4 | ERR_VALIDATION | Bad or missing arguments to the API | projects ls with no space |
Using exit codes in scripts
if trickest workflow get "$ID" > /dev/null 2>&1; then
echo "exists"
else
case $? in
2) echo "auth problem; re-login" ;;
3) echo "not found" ;;
4) echo "bad arguments" ;;
*) echo "api/unexpected error" ;;
esac
fiBackend-gated commands
Some commands are wired in the CLI but their server endpoint is not live yet. They
fail loudly — usually with HTTP 405 or "not supported by the backend" — and the
message names the alternative. This is a server gate, not a mistake on your end.
Known examples are called out on their respective pages (for instance
Schedules and the --sql flag on
Database).