Output Formats

Output Formats

What each command prints, where, and what the process exits with. Read this before wiring the CLI into a script or an agent.

The --output flag

--output is global and takes table (default) or json. It changes the output of three commands.

Command	--output table	--output json
devices	Table	Pretty JSON
events (the list, not its subcommands)	Table	Pretty JSON
config	Labelled lines	JSON object
metrics, admin usage-history export	Body verbatim	Body verbatim
raw	Pretty JSON, or the body verbatim for a text response	same
every other command	Pretty JSON	Pretty JSON

There is no CSV, YAML or template output and no column selection; use jq on the JSON.

JSON output

JSON is pretty-printed with a trailing newline and is the API response body unmodified: the CLI does not unwrap, rename or reshape it, so the shape is the API's. Check it against the API's OpenAPI document rather than assuming a key.

reportmateutil devices --output json | jq -r '.devices[] | [.serialNumber, .platform] | @tsv'

A success with an empty body prints null.

Text output

metrics (Prometheus exposition) and admin usage-history export (CSV) print the body exactly as received. If one of those endpoints answers with JSON instead, it is pretty-printed. export --out PATH writes the file and prints wrote N rows to PATH on stderr.

Table output

Tables use comfy-table's default ASCII style.

devices has four columns.

Column	Source key
Serial	serialNumber
Name	deviceName
Platform	platform
Last Seen	lastSeen

It accepts a bare array or an object with a devices array, and prints total: N below the table when the response carries total.

events has four columns, each from the first key present in the row.

Column	Keys tried, in order
Time	timestamp, ts, createdAt
Serial	serialNumber, device, deviceId
Kind	kind, eventType, status
Message	message, cut to 77 characters plus ... when longer than 80

Any value that is missing or not a JSON string renders as -, and an unrecognised response shape gives a header with no rows. An empty table is not proof of an empty fleet; re-run with --output json.

Streams and exit codes

Data goes to stdout. Errors go to stderr, prefixed Error:, with the method, path, HTTP status and full upstream body.

Error: GET /api/v1/devices -> 401 Unauthorized: {"detail":"..."}

Exit code	Meaning
0	Success, including --help and --version
1	Any runtime failure: a non-2xx response, network or TLS error, timeout, unparseable JSON, no endpoint or credential, or a local guard such as a missing --confirm
2	Command-line parsing error

There is no exit code per HTTP status; parse stderr to tell a 404 from a 500.

Piping

On Unix the CLI restores the default SIGPIPE behaviour, so closing the pipe early ends the process cleanly instead of panicking. The shell then reports the signal status (typically 141).

reportmateutil devices --output json | head -20