Output formats

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 envelope (default when stdout is piped or redirected, in CI, or with --no-input)	Scripting, AI agents, piping
pretty	Human-readable key-value pairs (default at an interactive terminal)	Quick inspection
table	Aligned columns with headers	Terminal viewing
ndjson	One compact JSON record per line	Streaming large lists
csv	Header row plus one row per record	Spreadsheet export

SHOPLAZZA_CLI_FORMAT pins the default (for example, SHOPLAZZA_CLI_FORMAT=json forces JSON in a pty); an explicit --format always wins. Only json is a stable contract: the other formats print the response body without the {"ok": true, "data": …} envelope, and pretty and table may shorten nested data, so don't parse them.

JSON

shell

shoplazza products list --format json

json

{
  "ok": true,
  "data": {
    "products": [...]
  }
}

Pretty

shell

shoplazza products list --format pretty

Displays key-value pairs for easy reading: identifying fields such as id, name, and title come first, nested objects are indented, and output is colored only at a terminal.

Table

shell

shoplazza products list --format table

Renders aligned columns with upper-case headers. Lists of orders, products, customers, and discounts show a curated set of columns; other lists flatten nested fields into dot-notation columns.

Filtering with --jq

Filter and transform JSON output using jq expressions. The expression runs against the full {"ok": true, "data": …} envelope, and --jq needs JSON output: at an interactive terminal, where the default is pretty, add --format json or the command fails with --jq requires --format json.

shell

# Extract product titles
shoplazza products list --format json --jq '.data.products[].title'

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

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

The -q flag is a shorthand alias for --jq. String results print without quotes.

Field projection with --fields

products +search supports --fields for choosing which product fields the API returns:

shell

shoplazza products +search --keyword "shirt" --fields "id,title,price_min" --format table

Other commands have no --fields; project with --jq instead.

Dry run

Preview the HTTP request without executing it:

shell

shoplazza products list --dry-run

This shows the method, path, URL, query parameters, 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 --params '{"product_id":"{}"}'

Success envelope

json

{
  "ok": true,
  "data": { ... }
}

When a newer CLI version is available or the Agent Skills are not installed, the JSON envelope also carries a top-level _notice object (update, skills) for agents. Set SHOPLAZZA_CLI_NO_NOTICE=1 to drop it.

Error envelope

json

{
  "ok": false,
  "error": {
    "type": "api",
    "message": "Product not found",
    "detail": {
      "status_code": 404,
      "request_id": "req_abc123"
    }
  }
}

At an interactive terminal with pretty or table output, errors print as a readable Error: line instead. See Error format for details.