---
title: "Exit codes"
description: "What the CLI returns, on which stream, and how a script should read it."
---

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

# Exit codes

[`--json` and `--text`](/cli/commands) pick how a command prints. This page is
about how a script reads what comes back.

## Streams

In text mode data goes to stdout and failures go to stderr, so a pipeline keeps
its data clean. In JSON mode the whole document goes to stdout, failures
included, so a caller parses one stream:

```json
{ "error": { "kind": "usage", "message": "..." } }
```

A usage mistake and a `404` read alike, which is what lets a caller learn the
format once.

## The response, unrendered

`--full` prints the API response exactly as it arrived:

```sh
minima entities get <entityId> --full
```

Lists are summarised in both text and JSON mode, so `--full` is the escape
hatch when you want the document untouched. It overrides the output mode rather
than combining with it — the same flag means the same thing whether the request
worked or not. For readable and complete, use `--json --full` and a formatter.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `2` | Usage error — a missing variable, an unknown flag, a bad argument |
| `3` | Not found (`404`) |
| `4` | Unauthorised or forbidden (`401`, `403`) |
| `5` | Any other API failure, or a mix of causes |
| `7` | Rate limited (`429`) |

[`push --apply`](/cli/workspace) reports its failures inside a normal document,
so a run where every write failed would read as success to anything checking
only that the command finished. Each failure carries the status that caused it,
and the run exits the way a single request with that status would — an expired
key is `4` whether it broke one write or forty. Mixed causes exit `5`.

## Colour and progress

Colour is on when stdout is a terminal, and progress is drawn in place only
when the line can safely be redrawn. Piping either command to a file gets plain,
single-pass output with no spinner frames in it.

| Variable | Effect |
|---|---|
| `NO_COLOR` | Any value turns colour off. |
| `MINIMA_PLAIN=1` | Turns off colour and in-place drawing together. |

An agent harness backed by a PTY looks like a person to a terminal check, so set
`MINIMA_PLAIN=1` if you get a transcript of every spinner frame instead of one
report.

Source: https://docs.minima.ltd/cli/output/index.mdx