Output and errors

The WyrdOS CLI is designed to be pleasant for humans and predictable for agents and scripts.

This page explains how output formats work, how TTY detection changes defaults, and what error responses look like.

Output formats

Most commands support an --output flag:

• --output table – human-friendly tables (good for terminals).
• --output json – machine-readable JSON (recommended for agents and scripts).
• --output csv – comma-separated values for exporting tabular data.

Example:

# Human-oriented view
wyrdos actions inbox --output table

# JSON for agents or scripts
wyrdos actions inbox --output json

TTY behaviour

The CLI adjusts its default output based on whether it is running in a TTY:

• TTY (interactive terminal) – defaults to a human-readable format (typically table or a pretty-printed view).
• Non-TTY (piped or redirected output) – defaults to JSON to make it safer for scripts and agents.

You can always override the default by passing --output explicitly.

Normalized error shape

Errors are returned in a consistent JSON structure so that agents and scripts can make decisions based on status and type.

Even when you are running in a TTY, you can force JSON error output with --output json.

The normalized error shape looks like:

{
  "error": true,
  "status": 401,
  "message": "Missing or invalid Authorization header"
}

Additional fields may be present depending on the endpoint and failure mode (for example, a code or details field), but error, status, and message are always present.

Recommendations for agents and scripts

• Always pass --output json and parse the response instead of scraping tables.
• Use the status field on errors to decide whether to retry, prompt for new credentials, or escalate.
• When chaining commands, treat non-zero exit codes as failures and inspect the JSON error body.