Skip to main content
This page explains how to pass JSON request bodies, read response payloads, handle errors, and supply query parameters that do not have a dedicated CLI flag.

​
Request bodies

Pass a request body with --body, in one of three forms:
  • An inline JSON string: --body '{"name":"Blob Sales"}'
  • A file path prefixed with @: --body @request.json
  • - to read from stdin: --body -
The CLI validates the body as JSON before sending it, so a malformed payload fails locally instead of round-tripping to the API first. Simple bodies can also be set field-by-field with a command’s promoted flags instead of --body (shown in that command’s --help output). The two approaches can’t be combined on the same call.
Run any command with --schema to print its arguments, flags, request body shape, and response shape without making an API call. For example:

​
Response payloads

A successful JSON response (--format json, the default when output is piped) contains the API’s payload, and --compact prints it non-indented. Response shapes vary by endpoint. For example, models list returns records with pagination metadata:
When pageInfo.hasNextPage is true, pass pageInfo.nextCursor to the next call’s --cursor flag. See model pagination for an example. Other endpoints can return resource-specific wrappers, arrays, or no response body; check the command’s --schema output. query run returns a newline-delimited JSON stream by default. Set resultType in its request body to request JSON rows, CSV, or XLSX instead. In --format json, the CLI passes the stream through unchanged. See Query commands. See output formats for how --format human renders these same payloads as tables and key-value summaries instead.

​
Errors

In --format json, an HTTP error response writes an error document to stderr:
In --format human, the same failure prints as a single line instead: Error: <detail> (HTTP <status>). See errors and exit codes for what a failure means for the process’s exit code. Local usage errors, such as an unknown command or a missing required flag, print plain text to stderr, even in JSON mode. Do not assume every failure produces JSON.

​
Query escape hatch

If the CLI’s generated flags for a command don’t cover a query parameter the API supports (for example, one added to the API after this CLI version was built), add it with the --query escape hatch instead. It’s repeatable, for multiple parameters:
Required query parameters that aren’t supplied, whether by a named flag or --query, cause the CLI to fail before sending a request, rather than letting the API reject an incomplete call.
A list command’s pagination flags (a cursor, a page size, or both) aren’t named consistently across every command. Check that command’s own --help output for the exact flag name.