Configuration Automation - Ping CLI

Logging

Ping CLI supports diagnostic logging to help developers troubleshoot issues and understand the CLI’s internal behavior. The default log level is WARN. To see more detailed output, set PINGCLI_LOG_LEVEL to DEBUG or INFO.

Enabling logging

Set the PINGCLI_LOG_LEVEL environment variable to control log verbosity:

export PINGCLI_LOG_LEVEL=DEBUG
pingcli pingone environments list

Log output is written to stderr by default.

Log levels

The following log levels are available, listed from most verbose to least verbose:

Level Description

DEBUG

Detailed operational messages useful for debugging, including API request and response metadata.

INFO

General informational messages confirming that Ping CLI is operating as expected.

WARN

Warnings about conditions that are not errors but may indicate unexpected behavior or configuration that should be reviewed. This is the default level.

ERROR

Error conditions that caused a command to fail or behave unexpectedly.

Writing logs to a file

To write log output to a file, set the PINGCLI_LOG_FILE environment variable:

export PINGCLI_LOG_LEVEL=DEBUG
export PINGCLI_LOG_FILE=./pingcli.log
pingcli pingone environments list

When PINGCLI_LOG_FILE is set, log messages are written to the specified file in NDJSON format with structured fields including timestamp, level, message, cli_function, and connector. This makes file logs suitable for ingestion into observability tooling.

File logging uses its own independent log level, controlled by PINGCLI_LOG_FILE_LEVEL (default: DEBUG). This lets you capture verbose file logs while keeping console output at a higher level.

If PINGCLI_LOG_FILE_LEVEL is set without PINGCLI_LOG_FILE, the CLI emits a warning and the value has no effect.

Using flags

All three log settings are also available as persistent flags on every command:

Flag Environment variable Default

--log-level

PINGCLI_LOG_LEVEL

WARN

--log-file

PINGCLI_LOG_FILE

Disabled

--log-file-level

PINGCLI_LOG_FILE_LEVEL

DEBUG

Precedence, from highest to lowest: flag > environment variable > profile configuration > default.

Persisting log settings in a profile

To avoid setting environment variables on every command, persist log settings using pingcli config set:

pingcli config set log.level=DEBUG
pingcli config set log.file=/path/to/file.ndjson
pingcli config set log.fileLevel=INFO

To configure settings for a specific profile, add the --profile flag:

pingcli config set --profile myprofile log.level=DEBUG

You can find a complete list of configuration keys in Configuration settings reference.

Learn more