# Output formats (/cli/output)

Commands that return structured API data support four formats. JSON is the default.

| Format | Output |
| - | - |
| `json` | Raw field names and values for scripts, agents, and `jq` |
| `table` | Formatted values for reading in a terminal |
| `yaml` | Raw values for YAML consumers |
| `text` | Formatted, tab-separated values without color or a list header |

Select a format for one command, save a default, or use an environment variable:

```bash
sim tables get tbl_9f3c1a05d4b7426e8c2f0917ab35de64 --output table
sim configure --set-output table
SIM_OUTPUT=yaml sim logs list > logs.yaml
```

`--output` can appear before or after the command. Commands use it when their action supports formatted output; the exceptions are listed below.

## What each format emits \[#what-each-format-emits]

### JSON and YAML \[#json-and-yaml]

Machine formats preserve API values: a duration remains `1500`, rather than the display string `"1.5s"`. Single-resource API responses are unwrapped from their outer `data` envelope. Cursor-paginated results retain rows under `data` and the continuation under `nextCursor`:

```json
{ "data": [{ "runId": "9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543" }], "nextCursor": null }
```

Read rows with `jq '.data[]'` and check `.nextCursor` for continuation. A null cursor means pagination is finished; inspect any command-specific truncation flags or notices too. See [Pagination](/cli/scripting#pagination) for limits and memory behavior.

### Tables and text \[#tables-and-text]

Tables show UTC timestamps without milliseconds, formatted sizes, `yes`/`no` booleans, and formatted monetary amounts. Each command's reference specifies its units. Long table cells are clipped to one line; use JSON or YAML to inspect the returned value in full.

Text uses the same formatted cells, flattened to one line and separated by tabs. Lists have no header or color; single records use a label and value on each line. Text values are not clipped to the table's column width:

```bash
sim files list --output text | while IFS=$'\t' read -r id name folder size type uploader uploaded; do
  printf '%s %s\n' "$id" "$name"
done
```

An absent value displays as an em dash in a table and an empty field in text. Use JSON when field types or empty-field positions matter.

## Separate results and diagnostics \[#separate-results-and-diagnostics]

Results go to stdout. Errors, progress, update notices, and operational notes go to stderr, so this pipe receives only the result:

```bash
sim logs list --output json | jq '.data[]'
```

In JSON/YAML mode, API errors use an `error` object on stderr with `code`, `message`, and optional `details`. Configuration errors, argument-parser errors, and some command outcome messages remain text. See [Exit codes](/cli/scripting#exit-codes) before branching on a command's outcome.

## Reading a run in detail \[#reading-a-run-in-detail]

In table mode, `sim logs get` prints a summary. Add `--trace` to print recursive spans with inputs, outputs, errors, timing, and cost:

```bash
sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --trace --output table
```

JSON and YAML include the returned trace without `--trace`; the flag does not change those formats:

```bash
sim logs get 9c4f0b7e-2d81-4a35-b6e9-70f1c8a2d543 --output json | jq '.traceSpans'
```

## Exceptions \[#exceptions]

| Command | Output behavior |
| - | - |
| `sim configure` | Prints local settings as text |
| `sim profiles` | Honors `--output`; JSON includes an `active` boolean |
| `sim telemetry status`, `enable`, `disable` | Always print text |
| `sim files get` | Streams file content to stdout; `--output-file` saves content and prints a save receipt |
| `sim chat` | Streams reply text in table/text modes and prints the conversation ID to stderr; JSON/YAML wait for the finished result including that ID |
| `sim workflows export` | Emits YAML when selected; otherwise emits JSON, including in table/text mode |

File downloads refuse binary content on an interactive terminal. Pipe stdout or use `--output-file`; overwriting an existing output file requires `--force`.

Workflow import accepts JSON. Pin that format when exporting a file you plan to import, even if your profile prefers YAML:

```bash
sim workflows export 3a9e21d8-5f47-4c0b-b2ea-91d7c6034ef8 --output json > wf.json
sim workflows import --workflow @wf.json
```

## Related docs \[#related-docs]

- [Configuration](/cli/configuration)
- [Scripting](/cli/scripting)
- [Logs commands](/cli/logs)
- [File commands](/cli/files)