-q, --query runs the JSON response through a jq filter and prints the results as raw values, one per line. It is mutually exclusive with --json.
On a list command, the filter runs against the same bare JSON array of resources that --json prints, so .[].metadata.id works on every list command:
Extract a single field
Get just the IDs from a list response:Reshape the output
Filters can transform the response into a new structure. Results that are not scalars (objects and arrays) print as compact JSON, one per line. The following collects each instance’sid and name into a single array:
Combine with an external jq
The output of -q is still valid JSON when the filter produces JSON, so you can pipe it into jq (or any other JSON-aware tool) for further processing:
Multiple filters
-q can be repeated. The filters’ results are zipped into one line per item: one result from each filter per line, space-separated, which is handy for tabular output:
Limit the results
--limit N cuts a list to its first N results before -q runs, so a select only sees those N. To cap the number of matches instead, slice inside the filter:
When a filter fails
An invalid filter makes the command exit with status 2. After acreate or update, the resource has already been saved by then, so the CLI prints the full payload to stdout and the error on stderr explains that only the filter failed.