> ## Documentation Index
> Fetch the complete documentation index at: https://docs.internal.nscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query output with -q

> Use jq filters to extract or reshape JSON responses without a second process.

`-q, --query` runs the JSON response through a [jq](https://jqlang.github.io/jq/) filter and prints the results as raw values, one per line. It is mutually exclusive with `--json`.

On a list command, the filter always runs against a bare JSON array of resources, so `.[].metadata.id` works on every list command. This holds even where `--json` wraps the array: `inferencing list-models` and `inferencing list-endpoints` emit `{"data":[...]}` under `--json`, but `-q` still sees the array:

```bash theme={null}
nscale inferencing list-models -q ".[].id"
```

On a command that returns one resource, the filter runs against that resource:

```bash theme={null}
nscale instances get <instance-id> -q ".status.status"
```

## Extract a single field

Get just the IDs from a list response:

```bash theme={null}
nscale instances list -q ".[].metadata.id"
```

Each filter result is printed on its own line, so the output flows naturally into shell loops:

```bash theme={null}
for id in $(nscale instances list -q ".[].metadata.id"); do
  nscale instances stop "$id" --yes
done
```

## 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's `id` and `name` into a single array:

```bash theme={null}
nscale instances list -q "[.[] | {id: .metadata.id, name: .metadata.name}]"
```

```json theme={null}
[{"id":"bed4405e-bd2f-491a-a515-3612e6d4230f","name":"instance-1"},{"id":"f1facb11-d3de-417f-92c0-dc582cea4c80","name":"instance-2"}]
```

Filter first, then project:

```bash theme={null}
nscale instances list -q '.[] | select(.status.status == "Active") | .metadata.id'
```

## 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:

```bash theme={null}
nscale projects list -q "[.[] | {id: .metadata.id, groupIDs: .spec.groupIDs}]" | jq "[.[] | .id]"
```

## 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:

```bash theme={null}
nscale instances list -q ".[].metadata.id" -q ".[].metadata.name" -q ".[].status.status"
```

```text theme={null}
bed4405e-bd2f-491a-a515-3612e6d4230f instance-1 Active
f1facb11-d3de-417f-92c0-dc582cea4c80 instance-2 Active
```

Output stops as soon as any filter runs out of results. When that happens, a warning is printed on stderr, unless the filter that ran out is the first one: a short first filter is deliberate, as in this example, which prints the count next to the first ID:

```bash theme={null}
nscale instances list -q "length" -q ".[].metadata.id"
```

## When a filter fails

An invalid filter makes the command exit with status 1. After a `create` 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.