> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Exit Codes

> Stable exit codes returned by the nullspace CLI, generated from the SDK source of truth.

Every `nullspace` CLI invocation exits with one of the stable codes
below. Agents and scripts can branch on the exit code without parsing
output; in `--json` mode the failure body additionally carries a
machine-readable `code` (see the
[error envelope](/error-codes)).

## Exit Codes

| Exit code | Name                    | Meaning               |
| --------: | ----------------------- | --------------------- |
|         0 | `SUCCESS`               | success               |
|         1 | `GENERIC_FAILURE`       | generic failure       |
|         2 | `USAGE_ERROR`           | usage error           |
|         3 | `NOT_FOUND`             | not found             |
|         4 | `UNAUTHENTICATED`       | unauthenticated       |
|         5 | `PERMISSION_DENIED`     | permission denied     |
|         6 | `QUOTA_OR_RATE_LIMITED` | quota or rate limited |
|         7 | `CONFLICT`              | conflict              |
|         8 | `MACHINE_RUNTIME_ERROR` | machine runtime error |

## How JSON Error Codes Map To Exit Codes

When a command fails, the machine-readable error `code` selects the
exit code. Exact mappings:

| Error code                    | Exit code |
| ----------------------------- | --------: |
| `machine_not_found`           |         3 |
| `not_found`                   |         3 |
| `snapshot_not_found`          |         3 |
| `template_not_found`          |         3 |
| `template_resource_not_found` |         3 |
| `missing_api_key`             |         4 |
| `unauthenticated`             |         4 |
| `unauthorized`                |         4 |
| `forbidden`                   |         5 |
| `permission_denied`           |         5 |
| `volume_read_only`            |         5 |
| `capacity_exceeded`           |         6 |
| `file_upload_limit_exceeded`  |         6 |
| `quota_exceeded`              |         6 |
| `rate_limit_exceeded`         |         6 |
| `volume_limit_exceeded`       |         6 |
| `volume_quota_exceeded`       |         6 |
| `conflict`                    |         7 |
| `incompatible_snapshot`       |         7 |
| `machine_not_ready`           |         7 |
| `rebuild_required`            |         7 |
| `snapshot_in_use`             |         7 |
| `upload_conflict`             |         7 |
| `volume_busy`                 |         7 |
| `exec_failed`                 |         8 |
| `exec_timeout`                |         8 |
| `timeout`                     |         8 |
| `invalid_fields`              |         2 |
| `invalid_request`             |         2 |
| `invalid_response`            |         2 |

Codes not listed above fall back to pattern rules, in order:

* `*_not_found` → 3 (not found)
* `*_permission_denied` → 5 (permission denied)
* codes containing `quota` or `rate_limit` → 6 (quota or rate limited)
* `*_conflict` → 7 (conflict)
* anything else → 1 (generic failure)

Usage errors raised by the CLI itself (bad flags, missing arguments)
exit with 2.

## Related

* [Error Codes](/error-codes) - the CLI JSON error envelope and
  edge/preview error anchors.
* [API Error Catalog](/reference/error-codes) - machine-readable error
  codes from the `ErrorResponse` schema.