Skip to main content
Every Omni CLI command that sends or receives data uses the same JSON conventions, whatever the command group. This page covers how to pass a request body, what a successful response looks like, what the CLI writes when a request fails, and how to reach a query parameter the CLI has no flag for.

​
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 response (--format json, the default when output is piped) is the API’s JSON body, unmodified, and --compact prints it non-indented, which is easier to pipe into jq or other tools. List endpoints return one of two shapes:
A single-resource endpoint (get, create, update, delete) returns that resource’s JSON object directly, with no wrapper. See output formats for how --format human renders these same payloads as tables and key-value summaries instead.

​
Errors

A failed request writes nothing to stdout, even a partial response body, and writes exactly one JSON 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.

​
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.