Configuration Automation - Ping CLI

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.

pingcli <command> -O json
pingcli <command> -O ndjson
pingcli <command> -O ndjson-wrapped
pingcli <command> -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).

pingcli config profiles list
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.

pingcli config profiles list -O 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 for the complete field reference and JSONSchema.

Filtering with --query

The --query flag applies a JMESPath 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.

# Get the name of every active profile
pingcli config profiles list -O json --query 'data[?active].name'
[
  "development-environment"
]

Refer to Filtering and transforming output for more --query examples and JMESPath syntax.

Piping to jq

For transformations that go beyond what JMESPath supports, pipe to jq:

# Extract all profile names as a plain list
pingcli config profiles list -O json | jq -r '.data[].name'
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.

pingcli config profiles list -O ndjson
{"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

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

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

pingcli config profiles list -O ndjson-wrapped
{"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:

pingcli config profiles list -O ndjson-wrapped --query 'data.name'
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:

pingcli config set outputFormat json

You can override the configured default at any time with the -O flag on individual commands.

Learn more