> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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.