# Options and output

Discover commands, use global flags, parse JSON output, follow pagination, and distinguish API failures from CLI parser errors.

Use command help as the source of truth for the installed CLI. API field names and CLI flag names are not always the same.

## First command

```bash
zernio --help
zernio posts:update --help
```

The first command lists available commands. The second prints positional arguments, supported flags, and required inputs without updating a post.

## Commands

These options work across commands:

| Option | Result |
|---|---|
| `--help`, `-h` | Print help |
| `--version`, `-v` | Print the installed CLI version |
| `--pretty` | Indent JSON output |

JSON is already the default. There is no global `--json`, `--token`, `--body`, or `--yes` flag. Supply credentials through [authentication](/cli/authentication) and use only the flags registered by each command.

## Inputs

| Input shape | Example | Rule |
|---|---|---|
| Positional ID | `zernio posts:get "$POST_ID"` | Order matters; discover the ID first |
| Comma-separated IDs | `--accounts "$ACCOUNT_ID,$OTHER_ACCOUNT_ID"` | Used by `posts:create` |
| JSON value | `--media-json '[{"type":"image","url":"https://example.com/photo.jpg"}]'` | Quote JSON as one shell argument |
| Command-specific field | `--text` on create; `--content` on update | Do not infer from API field names |

Generated commands can have longer names, such as `adcampaigns:list-ad-campaigns`. Do not shorten them to match another command group.

## Output and errors

Capture API output and the exit status before parsing. This example reads only:

```bash
if zernio accounts:list > accounts.json 2> cli-error.txt; then
  jq '.accounts' accounts.json
else
  printf '%s\n' 'CLI request failed; inspect cli-error.txt' >&2
fi
```

Command-handler failures normally exit `1` and write this shape to stderr:

```json
{"error":true,"message":"Request failed","status":403}
```

`status` is optional. This is the CLI error wrapper, not the original API response body. Do not depend on API-only fields being present in stderr.

Help and version output are text. Unknown commands, unknown flags, and missing required inputs produce parser diagnostics, not this JSON shape. `auth:login` also writes text progress to stderr.

## Pagination

| Command | Pagination inputs | Continue with |
|---|---|---|
| `posts:list` | `--page`, `--limit` | Next page number; defaults are page 1, limit 10 |
| `analytics:posts` | `--page`, `--limit` | Next page number; default limit is 50 |
| `inbox:conversations` | `--cursor`, `--limit` | Returned `pagination.nextCursor` while `hasMore` is true; default limit is 20 |

Check each response and command help. Pagination is not uniform across groups, and the CLI does not fetch every page automatically.

## How it behaves

- `--pretty` changes formatting, not response fields.
- A zero exit status means the handler succeeded, not that every asynchronous operation completed. Inspect response statuses and per-target results.
- Errors can include private request details. Redact credentials and customer data before sharing logs.
- If a documented API field has no CLI flag, use the API or SDK rather than inventing a flag.

## Related

- [Authentication](/cli/authentication)
- [Posting commands](/cli/posting)
- [CLI for agents](/cli/agents)
- [Rate limits](/guides/rate-limits)