Configuration Automation - Ping CLI

Return codes

Ping CLI exits with a numeric return code after every command. Scripts and CI/CD pipelines can use these codes to branch on success, failure, or success-with-warnings without parsing output text.

Code

Meaning

When you see it

0

Success

The command completed with no errors or warnings. Also returned for non-operational commands: --help, --version, and completion.

1

Failure

The command encountered an error and did not complete successfully. Check stderr or the log file for details.

2

Success with warnings

The command completed, but one or more non-fatal issues were encountered. Only returned when --detailed-exitcode is enabled; otherwise these commands return 0.

Enabling detailed exit codes

By default, Ping CLI returns 0 for any command that completes, even if warnings were produced. To distinguish a clean success from a success-with-warnings, pass the --detailed-exitcode (-D) flag:

pingcli --detailed-exitcode <command>

With --detailed-exitcode enabled:

  • A clean run returns 0.

  • A run that completed but produced warnings returns 2.

  • A run that failed returns 1.

Without the flag, both clean runs and runs-with-warnings return 0.

When warnings occur

Warnings are non-fatal: the command finishes, but something worth noting happened. Common causes include:

  • Partial API access: a resource couldn’t be read because the API returned 403 Forbidden or 204 No Content for that item, while other items succeeded.

  • Partial bulk operation failures: a batch operation completed for most items but failed for some.

  • Missing resources during cleanup: a delete or cleanup operation encountered a resource that no longer existed.

In all cases the command exits with 0 by default, or 2 when --detailed-exitcode is set.

Pipe stderr to your log file or CI output to capture the warning messages alongside the exit code.

Using return codes in shell scripts

Checking $? after a pingcli command lets you branch on the result without inspecting output text.

Fail on error, continue on warning

pingcli --detailed-exitcode pingone groups list
exit_code=$?

if [ "$exit_code" -eq 1 ]; then
  echo "Command failed. Check the logs." >&2
  exit 1
elif [ "$exit_code" -eq 2 ]; then
  echo "Command completed with warnings. Review output before continuing."
else
  echo "Success."
fi

Treat any non-zero result as a failure

If you want to stop on warnings as well as errors, use --detailed-exitcode and check for any non-zero code:

set -e
pingcli --detailed-exitcode pingone environments list

Or check explicitly:

pingcli --detailed-exitcode pingone environments list
if [ $? -ne 0 ]; then
  echo "Unexpected result — aborting." >&2
  exit 1
fi

Using detailed exit codes in GitHub Actions

The 2 (warning) exit code is useful in CI when you want to flag issues without failing the build. The example below captures warnings as a job summary but lets the workflow continue:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Export PingOne configuration
        id: export
        run: |
          pingcli --detailed-exitcode pingone environments list
          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
        continue-on-error: true

      - name: Fail on error
        if: steps.export.outputs.exit_code == '1'
        run: |
          echo "::error::Ping CLI command failed. Check the step logs for details."
          exit 1

      - name: Annotate warnings
        if: steps.export.outputs.exit_code == '2'
        run: |
          echo "::warning::Ping CLI completed with warnings. Review the export output."

In this pattern:

  • continue-on-error: true prevents GitHub Actions from immediately failing the job so the subsequent steps can inspect the exit code.

  • Exit code 1 causes an explicit job failure with an error annotation.

  • Exit code 2 surfaces a warning annotation in the Actions UI without failing the pipeline.

Learn more