--- title: "Output Formats & Exit Codes" canonical: https://trickest.com/docs/developer-tools/cli/output-and-exit-codes description: "Terminal and JSON output, global flags, stderr error formats, and exit codes for Trickest CLI scripts." --- # Output Formats & Exit Codes Use JSON output to parse results and exit codes to handle failures in scripts. This page covers output formats, global flags, and structured errors, including commands that need `--quiet` to produce JSON without status lines. ## Select JSON for scripts Output helpers default to **tables in an interactive terminal** and **JSON when stdout is piped or redirected**. JSON is compact when piped and indented in a terminal. Set `--output json --quiet` in scripts instead of relying on terminal detection. Most list commands return arrays; see [Output-shape caveats](#output-shape-caveats) for exceptions. ```bash trickest --output json --quiet space ls ``` ```json [{"name":"Solutions","id":"5c57db3d-…","description":"…","created":"2025-12-29T16:10:55Z"}, …] ``` Pipe results to `jq` to select fields or filter records: ```bash trickest space ls | jq -r '.[].name' trickest run get | jq '.nodes[] | select(.status != "SUCCEEDED")' ``` ## Global flags Place global flags **before** the subcommand so the root command can parse them: ```bash trickest --output table node ls # correct ``` | Flag | Effect | |---|---| | `--output ` | Select output format. Default: table in a terminal, JSON when piped. | | `--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` | Preview changes without applying them on commands that support dry-run. | | `-V, --version` | Print the CLI version. | | `-h, --help` | Show help at any level. | ### Format examples Table (human-friendly): ```bash trickest --output table space ls ``` ```text ┌──────────────────┬──────────────────────────────────────┬─────────────────────────────┐ │ Name │ ID │ Created │ ├──────────────────┼──────────────────────────────────────┼─────────────────────────────┤ │ Solutions │ 5c57db3d-9f2e-4c1a-b7d4-6a58e02d913c │ 2025-12-29T16:10:55.856630Z │ └──────────────────┴──────────────────────────────────────┴─────────────────────────────┘ ``` YAML: ```bash trickest --output yaml space ls ``` ```yaml - name: Solutions id: 5c57db3d-9f2e-4c1a-b7d4-6a58e02d913c description: "" created: 2025-12-29T16:10:55.856630Z ``` ## Output-shape caveats Check the command's response shape before writing a `jq` filter: `trickest tool list` returns the raw paginated API envelope: ```json {"next":"…page=2…","previous":null,"page":1,"last":15,"count":281,"results":[ … ]} ``` Use `jq '.results[]'` to read records and follow `next` for further pages. `trickest search ` returns results grouped by type. In `--output table` it prints sections like `library (5)` and `Tools (5)`. Commands like `memory set` emit a human line (`Memory entry created: `) **and** the JSON object. If you're parsing stdout as JSON, add `--quiet` to keep only the JSON: ```bash trickest --quiet memory set mykey "value" ``` ## The error envelope Handled errors go to **stderr**. When stderr is piped or redirected, the error handler writes this JSON shape: ```json {"code":"ERR_NOT_FOUND","message":"…human-readable, often with the fix…","hint":"…or null…"} ``` In a terminal, the handler prints text. The `--output` flag selects command results, not the error format. Unknown commands, unknown options, and missing required arguments also produce parser text, even with redirected stderr. Read `message` and `hint` before retrying. They can name a supported alternative, such as using `workflow get ` and reading `schedule_info`. ## Exit codes Branch on these in scripts. They are stable and distinct per error class: | Exit | Code(s) | Meaning | Example trigger | |---|---|---|---| | `0` | None | Success | `trickest space ls` | | `1` | `ERR_API`, `ERR_UNEXPECTED` | Backend/HTTP error, or a backend-gated feature | See [sandbox client compatibility](/docs/developer-tools/cli/sandbox) for affected session commands | | `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 | A request fails API validation | | `4` | Parser text | Unknown command, option, or missing required argument | `trickest unknown-command` | | `5` | `ERR_CONFLICT` | Resource state conflict | An API conflict response | | `6` | `ERR_FORBIDDEN` | Permission denied | An API permission rejection | | `7` | `ERR_RATE_LIMITED` | Rate limit reached | An API rate-limit response after retries | ### Using exit codes in scripts ```bash 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 fi ``` ## Backend-gated commands Some commands exist in the CLI but depend on platform support. Unsupported operations can return HTTP 405 or "not supported by the backend". Check the error message and the command's reference page for an alternative. Examples include `fleet rm` / `fleet scale` on [Fleet](/docs/developer-tools/cli/fleet), and `schedule ls` / `get` / `enable` / `disable` on [Schedules](/docs/developer-tools/cli/schedules). ## Related The active context that drives ERR_NOT_FOUND on workflow commands. Every command at a glance. --- _Markdown source of https://trickest.com/docs/developer-tools/cli/output-and-exit-codes._