---
title: Return codes
description: 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.
component: pingcli
version: 1.0
page_id: pingcli:using_pingcli:return-codes
canonical_url: https://developer.pingidentity.com/pingcli/1.0/using_pingcli/return-codes.html
revdate: June 5, 2026
section_ids:
  enabling-detailed-exit-codes: Enabling detailed exit codes
  when-warnings-occur: When warnings occur
  using-return-codes-in-shell-scripts: Using return codes in shell scripts
  fail-on-error-continue-on-warning: Fail on error, continue on warning
  treat-any-non-zero-result-as-a-failure: Treat any non-zero result as a failure
  using-detailed-exit-codes-in-github-actions: Using detailed exit codes in GitHub Actions
  learn-more: Learn more
---

# 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](logging.html) 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:

```bash
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

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

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

Or check explicitly:

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

```yaml
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

* [pingcli pingone groups list](../command_reference/pingcli_pingone_groups_list.html)

* [pingcli pingone environments list](../command_reference/pingcli_pingone_environments_list.html)

* [Configuration settings reference](../settings_reference/configuration-settings-reference.html)

* [Output formats](output-formats.html)

* [Logging](logging.html)