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

# How to filter CLI output with JSONPath

Most CLI commands that return data support the `--format jsonpath='<expression>'` parameter. You can use it to extract values, such as a resource ID, name or IP address, without post-processing the full output.

For example, to return only the ID of a virtual machine (VM), add the following parameter to the `nebius compute instance create` command:

```bash theme={null}
--format jsonpath='{.metadata.id}'
```

The CLI uses the [same JSONPath implementation](https://kubernetes.io/docs/reference/kubectl/jsonpath/) as `kubectl`. This implementation extends the original JSONPath syntax with additional functions, such as list iteration, but it doesn't support all JSONPath features.

## Syntax

A JSONPath expression selects values from the JSON object returned by a CLI command.

When you write JSONPath expressions for the `--format jsonpath` parameter, consider the following:

* Enclose expressions in curly braces. However, if you omit them, the CLI still parses the value.

  The `$` operator is optional because expressions start from the root object by default.

  As a result, these expressions are equivalent:

  ```bash theme={null}
  --format jsonpath='{$.metadata.id}'
  ```

  ```bash theme={null}
  --format jsonpath='{.metadata.id}'
  ```

  ```bash theme={null}
  --format jsonpath='.metadata.id'
  ```

* Use double quotes to quote literal text inside JSONPath expressions:

  ```bash theme={null}
  --format jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.state}{"\n"}{end}'
  ```

* Use the `range` and `end` operators to iterate over lists:

  ```bash theme={null}
  --format jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}'
  ```

* To step backward through a list, use negative slice indices. The negative indices don't wrap around a list and are valid if `-index + listLength >= 0`. For example:

  ```bash theme={null}
  nebius compute instance list --format jsonpath='{.items[-1:].metadata.name}'
  ```

* Complex values, such as objects or lists, are printed in their string representation. If you need stable machine-readable output for further processing, use `--format json`.

## Common expressions

| Expression                                     | Description                                                                              |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `{@}`                                          | Returns the current object.                                                              |
| `{.metadata.name}`                             | Returns the `metadata.name` value.                                                       |
| `{.items[0]}`                                  | Returns the first item from the `items` list.                                            |
| `{.items[-1:]}`                                | Returns the last item from the `items` list.                                             |
| `{.items[*].metadata.name}`                    | Returns the `metadata.name` value for all items in the `items` list.                     |
| `{.items[*]['metadata.name', 'status.state']}` | Returns the `metadata.name` and `status.state` values for all items in the `items` list. |
| `{range .items[*]}...{end}`                    | Iterates over the `items` list.                                                          |

For more information, see the examples below and [Kubernetes JSONPath documentation](https://kubernetes.io/docs/reference/kubectl/jsonpath/#functions).

## Examples

### Getting a value from a single resource

Below are several examples of how to get a value from a single resource:

* Get a name of a VM:

  ```bash theme={null}
  nebius compute instance get \
     --id <VM_ID> \
     --format jsonpath='{.metadata.name}'
  ```

  Example output:

  ```text theme={null}
  vm1
  ```

* Get a status of a VM:

  ```bash theme={null}
  nebius compute instance get \
     --id <VM_ID> \
     --format jsonpath='{.status.state}'
  ```

  Example output:

  ```text theme={null}
  RUNNING
  ```

* Get a bucket ID by the bucket name:

  ```bash theme={null}
  nebius storage bucket get-by-name \
     --name <bucket_name> \
     --format jsonpath='{.metadata.id}'
  ```

  Example output:

  ```text theme={null}
  storagebucket-***
  ```

* Get a public IP address of a VM by the VM name:

  ```bash theme={null}
  nebius compute instance get-by-name \
     --name <VM_name> \
     --format jsonpath='{.status.network_interfaces[0].public_ip_address.address}'
  ```

  Example output:

  ```text theme={null}
  203.0.113.10/32
  ```

### Getting values from a list

Below are several examples of how to get values from a list:

* Get the name of the first VM from the list:

  ```bash theme={null}
  nebius compute instance list --format jsonpath='{.items[0].metadata.name}'
  ```

  Example output:

  ```text theme={null}
  vm2
  ```

* Get names and statuses of all VMs:

  ```bash theme={null}
  nebius compute instance list \
     --format jsonpath="{.items[*]['metadata.name', 'status.state']}"
  ```

  Example output:

  ```text theme={null}
  vm2 vm1 RUNNING RUNNING
  ```

### Formatting list output

Print each VM name and status on a separate line:

```bash theme={null}
nebius compute instance list \
   --format jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.state}{"\n"}{end}'
```

Example output:

```text theme={null}
vm2   RUNNING
vm1   RUNNING
```

## Limitations

JSONPath regular expressions aren't supported. In this context, a *regular expression* is a pattern used in a JSONPath filter to match field values. For example, the following expression tries to find VMs whose names start with `vm`:

```bash theme={null}
nebius compute instance list \
   --format jsonpath='{.items[?(@.metadata.name=~/^vm/)].metadata.name}'
```

This expression doesn't work because the JSONPath implementation used by the CLI doesn't support the `=~` regular expression match operator. The command fails while parsing the JSONPath expression, before matching it against command output.

Match values with regular expressions by using `jq`:

```bash theme={null}
nebius compute instance list --format json \
   | jq -r '.items[] | select(.metadata.name | test("^vm")) | .metadata.name'
```

This command requires `jq` to be installed.

Example output:

```text theme={null}
vm2
vm1
```