---
title: "CLI Exit Codes"
url: "https://docs.caracal.run/reference/runtime-exit-codes/"
markdown_url: "https://docs.caracal.run/markdown/reference/runtime-exit-codes.md"
description: "Exit behavior for top-level caracal runtime CLI commands and Console launch."
page_type: "reference"
concepts: []
requires: []
---

# CLI Exit Codes

Canonical URL: https://docs.caracal.run/reference/runtime-exit-codes/
Markdown URL: https://docs.caracal.run/markdown/reference/runtime-exit-codes.md
Description: Exit behavior for top-level caracal runtime CLI commands and Console launch.
Page type: reference
Concepts: none
Requires: none

---

Top-level `caracal` commands are limited to local runtime lifecycle, status, purge, `run`, and Console launch.

## Exit Behavior

| Command | Success | Failure |
| --- | --- | --- |
| `caracal up` | `0` after stack start succeeds. | Non-zero when Compose/build/start fails. |
| `caracal down` | `0` after stack stop succeeds. | Non-zero when Compose stop fails. |
| `caracal status` | `0` when health probes pass. | `1` when service health fails. |
| `caracal status --ready` | `0` when readiness probes pass. | `1` when dependency readiness fails. |
| `caracal purge` | `0` after selected state is removed. | Non-zero when cleanup fails. |
| `caracal run -- <command>` | Child process exit code after credentials are acquired. | Non-zero before spawn when config, credential exchange, step-up, or governance fails. |
| `caracal console` | Console process exit code. | Non-zero when Console launcher or TTY requirements fail. |

## Structured Output

`caracal status --json` emits machine-readable status. Console-owned diagnostics are available through the Console `diagnostics` view and management command catalog, not as top-level runtime CLI workflows.

## Next Step

Use [Compatibility](/reference/compatibility/) before changing supported runtime, package manager, deployment, or docs build targets.

## Related Pages

- [Choose the Right Surface](/runtime-console/cli-and-console/)
- [Start and Check the Stack](/runtime-console/stack/)
- [Run Workloads](/runtime-console/runtime/)