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:

--format jsonpath='{.metadata.id}'

The CLI uses the same JSONPath implementation 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:
--format jsonpath='{$.metadata.id}'
--format jsonpath='{.metadata.id}'
--format jsonpath='.metadata.id'

Use double quotes to quote literal text inside JSONPath expressions:

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

Use the range and end operators to iterate over lists:

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

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:

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

Example output:

vm1

Get a status of a VM:

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

Example output:

RUNNING

Get a bucket ID by the bucket name:

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

Example output:

storagebucket-***

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

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

Example output:

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:

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

Example output:

vm2

Get names and statuses of all VMs:

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

Example output:

vm2 vm1 RUNNING RUNNING

Formatting list output

Print each VM name and status on a separate line:

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

Example output:

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:

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:

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:

vm2
vm1

Developer tools in Nebius AI Cloud

CLI

Terraform provider

REST API

gRPC API

Agent Resources

How to filter CLI output with JSONPath

Syntax

Common expressions

Examples

Getting a value from a single resource

Getting values from a list

Formatting list output

Limitations

​Syntax

​Common expressions

​Examples

​Getting a value from a single resource

​Getting values from a list

​Formatting list output

​Limitations

Syntax

Common expressions

Examples

Getting a value from a single resource

Getting values from a list

Formatting list output

Limitations