# Output formats

> Shape Shoplazza CLI output: pick json, pretty, or table with --format, filter with --jq, project columns with --fields, and preview a call with --dry-run.

Shoplazza CLI supports multiple output formats and filtering options for flexible data handling.

## Format flag

Use the global `--format` flag on any command:

```shell
shoplazza products +search --keyword "shirt" --format <format>
```

| Format | Description | Best for |
|--------|-------------|----------|
| `json` | Structured JSON (default) | Scripting, AI agents, piping |
| `pretty` | Human-readable key-value pairs | Quick inspection |
| `table` | Tab-separated table with headers | Terminal viewing |

### JSON (default)

```shell
shoplazza products list
```

```json
{
  "ok": true,
  "action": "products.list",
  "data": {
    "products": [...]
  }
}
```

### Pretty

```shell
shoplazza products list --format pretty
```

Displays sorted key-value pairs for easy reading.

### Table

```shell
shoplazza products list --format table
```

Renders a tab-separated table with column headers.

## Filtering with --jq

Filter and transform JSON output using jq expressions:

```shell
# Extract product titles
shoplazza products list --jq '.data.products[].title'

# Select specific fields
shoplazza orders list --jq '.data.orders[] | {id, status, total_price}'

# Count results
shoplazza products list --jq '.data.products | length'
```

The `-q` flag is a shorthand alias for `--jq`.

## Field projection with --fields

Shortcuts support `--fields` for selecting output columns:

```shell
shoplazza products +search --keyword "shirt" --fields "id,title,price" --format table
```

## Dry run

Preview the HTTP request without executing it:

```shell
shoplazza products list --dry-run
```

This shows the method, URL, headers, and body that would be sent, without making the actual API call. Useful for debugging and learning the API.

## Output conventions

### stdout vs stderr

* **stdout** — Data output (JSON envelopes). Safe to pipe and parse.
* **stderr** — Progress indicators, warnings, and hints. Human-readable.

This separation ensures you can safely pipe CLI output:

```shell
shoplazza products list --jq '.data.products[].id' | xargs -I {} shoplazza products get --id {}
```

### Success envelope

```json
{
  "ok": true,
  "action": "products.list",
  "data": { ... }
}
```

### Error envelope

```json
{
  "error": {
    "type": "api",
    "message": "Product not found",
    "hint": "Check the product ID and try again"
  },
  "request_id": "req_abc123"
}
```

See [Error format](../reference/error-format) for details.