# Output and scripting

Commands follow the pattern `fob-zb resource action [id] [options]`. Run `fob-zb resource` to see a resource's actions, or add `--help` to any command.

## Output formats

| You want | Use | Notes |
| --- | --- | --- |
| A readable table | *(default)* | One page of results, with a hint when there are more |
| Raw JSON of one page | `--json` | Zoho's records as returned, for the current page |
| Every row as JSON | `--format json` | Fetches all pages, wrapped as `{"invoices": […]}` |
| Every row as CSV | `--format csv` | Fetches all pages. Use it for spreadsheets |
| Chosen columns | `--fields a,b,c` | Works with table and CSV |
| Write to a file | `--output file` | Data goes to the file. The "Wrote file" notice goes to stderr |

`--format json` and `--format csv` fetch up to 15,000 rows. If a result is cut off, fob-zb says so on stderr. Narrow it with filters.

## Pagination

Tables and `--json` return one page: `--page` (default 1) and `--per-page` (default and maximum 200).

```bash
fob-zb contacts list --page 2 --per-page 50
```

## Filters

Each `list` has its own filters. Check `--help`, for example:

```bash
fob-zb invoices list --status overdue --customer 4600xxxxxxx
fob-zb bank-transactions list --account-id 4600xxxxxxx --status uncategorized
fob-zb contacts list --type vendor --search acme
```

Zoho allows only one of `--type` and `--status` on `contacts list`.

## Piping and scripting

Data goes to stdout and messages go to stderr, so pipes stay clean:

```bash
# Total outstanding across overdue invoices
fob-zb invoices list --status overdue --format json \
  | jq '[.invoices[].balance] | add'

# Overdue invoices to a spreadsheet
fob-zb invoices list --status overdue --format csv \
  --fields invoice_number,customer_name,due_date,balance --output overdue.csv
```

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Error: an API, credential or validation failure. The message is printed to stderr as `Error: …` |

Set `FOB_DEBUG=1` to print stack traces as well.