--- title: Output formats description: "Ping CLI can produce output in four formats: text, json, ndjson, and ndjson-wrapped. Use the -O flag (or --output-format) to choose. The format you pick determines what downstream tools you can combine with and how much processing you need to do." component: pingcli version: 1.0 page_id: pingcli:using_pingcli:output-formats canonical_url: https://developer.pingidentity.com/pingcli/1.0/using_pingcli/output-formats.html revdate: June 8, 2026 section_ids: text: text json: json filtering-with-query: Filtering with --query piping-to-jq: Piping to jq ndjson: ndjson when-to-prefer-ndjson-over-json: When to prefer ndjson over json processing-ndjson-in-a-shell-loop: Processing ndjson in a shell loop filtering-ndjson-with-query: Filtering ndjson with --query ndjson-wrapped: ndjson-wrapped setting-a-default-output-format: Setting a default output format learn-more: Learn more --- # Output formats Ping CLI can produce output in four formats: `text`, `json`, `ndjson`, and `ndjson-wrapped`. Use the `-O` flag (or `--output-format`) to choose. The format you pick determines what downstream tools you can combine with and how much processing you need to do. ```bash pingcli -O json pingcli -O ndjson pingcli -O ndjson-wrapped pingcli -O text ``` | | | | | ---------------- | --------------------------------------------------------- | ----------------------------------------------------- | | ***Format*** | ***Best for*** | ***Works with*** | | `text` (default) | Reading output at the terminal | Human eyes; no tooling required | | `json` | Scripting, automation, complete response inspection | `jq`, `--query` (JMESPath), Python, any JSON parser | | `ndjson` | Streaming, log pipelines, processing one record at a time | `jq`, `while read`, grep, awk, log shippers | | `ndjson-wrapped` | Streaming with full envelope metadata for each record | `jq`, log shippers that expect a consistent structure | ## text Text is the default. Ping CLI formats the response as an aligned table with column headers (easy to scan, but not designed for parsing). ```bash pingcli config profiles list ``` ```text NAME DESCRIPTION ACTIVE default Default profile created by Ping CLI false development-environment CLI profile for the feature development environment true testing-environment CLI profile for the testing environment false ``` Text output does not support `--query`. If you need to filter or extract values, switch to `json` or `ndjson`. ## json JSON wraps every command result in a consistent envelope. The six core fields (`schemaVersion`, `status`, `message`, `data`, `errors`, `meta`) are always present. A `warnings` field is included only when the command completes with non-fatal warnings. ```bash pingcli config profiles list -O json ``` ```json { "schemaVersion": "1.0", "status": "success", "message": "", "data": [ { "name": "default", "description": "Default profile created by Ping CLI", "active": false }, { "name": "development-environment", "description": "CLI profile for the feature development environment", "active": true }, { "name": "testing-environment", "description": "CLI profile for the testing environment", "active": false } ], "errors": [], "meta": { "command": "pingcli config profiles list", "count": 3 } } ``` `data` holds the command payload: an array when the command returns multiple records, a single object for single-resource commands, or `null` on error. `meta.count` is automatically set whenever `data` is an array. Refer to [JSON output schema reference](../output_schema_reference/output-schema-reference.html) for the complete field reference and JSONSchema. ### Filtering with --query The `--query` flag applies a [JMESPath](https://jmespath.org/) expression to the full JSON envelope. This is the fastest way to extract a specific field or filter records without installing additional tools. Because `--query` targets the envelope, reference `data` as the root for command results. ```bash # Get the name of every active profile pingcli config profiles list -O json --query 'data[?active].name' ``` ```json [ "development-environment" ] ``` Refer to [Filtering and transforming output](filtering-output.html) for more `--query` examples and JMESPath syntax. ### Piping to jq For transformations that go beyond what JMESPath supports, pipe to `jq`: ```bash # Extract all profile names as a plain list pingcli config profiles list -O json | jq -r '.data[].name' ``` ```text default development-environment testing-environment ``` ## ndjson Newline-delimited JSON (NDJSON) emits one raw JSON record for each line as each result is produced. Each line is a plain JSON object; there is no envelope wrapper. ```bash pingcli config profiles list -O ndjson ``` ```text {"name":"default","description":"Default profile created by Ping CLI","active":false} {"name":"development-environment","description":"CLI profile for the feature development environment","active":true} {"name":"testing-environment","description":"CLI profile for the testing environment","active":false} ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Errors are always wrapped in the full envelope regardless of which NDJSON format you use. Use `-O ndjson-wrapped` if you need a full envelope on every line. | ### When to prefer ndjson over json * **Streaming**: Records appear as they arrive rather than after the full response is buffered. Useful for long-running commands. * **Log pipelines**: NDJSON feeds directly into log shippers (Fluentd, Logstash, Vector) without any wrapping. * **Line-by-line processing**: Standard shell tools (`grep`, `awk`, `while read`) work on individual lines without needing to parse a document. ### Processing ndjson in a shell loop ```bash pingcli config profiles list -O ndjson | while IFS= read -r line; do name=$(echo "$line" | jq -r '.name') active=$(echo "$line" | jq -r '.active') echo "Profile: $name active=$active" done ``` ```text Profile: default active=false Profile: development-environment active=true Profile: testing-environment active=false ``` ### Filtering ndjson with --query With bare `-O ndjson`, `--query` applies a JMESPath expression to each raw record individually. Because there is no envelope, reference fields directly by name: ```bash # Print only the name field from every record pingcli config profiles list -O ndjson --query 'name' ``` ## ndjson-wrapped `-O ndjson-wrapped` behaves like `ndjson` but wraps each record in the full envelope. Use this format when downstream tools need envelope metadata (such as `status` or `meta.command`) alongside every record. ```bash pingcli config profiles list -O ndjson-wrapped ``` ```text {"schemaVersion":"1.0","status":"success","message":"","data":{"name":"default","description":"Default profile created by Ping CLI","active":false},"errors":[],"meta":{"command":"pingcli config profiles list","count":1}} {"schemaVersion":"1.0","status":"success","message":"","data":{"name":"development-environment","description":"CLI profile for the feature development environment","active":true},"errors":[],"meta":{"command":"pingcli config profiles list","count":1}} {"schemaVersion":"1.0","status":"success","message":"","data":{"name":"testing-environment","description":"CLI profile for the testing environment","active":false},"errors":[],"meta":{"command":"pingcli config profiles list","count":1}} ``` With `--query` or `jq`, reference fields through the envelope: ```bash pingcli config profiles list -O ndjson-wrapped --query 'data.name' ``` ```bash pingcli config profiles list -O ndjson-wrapped | jq -r 'select(.data.active) | .data.name' ``` ## Setting a default output format To avoid specifying `-O` on every command, set a default in your configuration: ```bash pingcli config set outputFormat json ``` You can override the configured default at any time with the `-O` flag on individual commands. ## Learn more * [pingcli config profiles list](../command_reference/pingcli_config_profiles_list.html) * [pingcli config set](../command_reference/pingcli_config_set.html) * [Configuration settings reference](../settings_reference/configuration-settings-reference.html) * [Filtering and transforming output](filtering-output.html) * [JSON output schema reference](../output_schema_reference/output-schema-reference.html) * [Return codes](return-codes.html)