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

# Reference: flags, modes, and exit codes

> Global flags, output modes for agents and CI, introspection with --describe, exit codes, environment variables, and maintenance commands of the Jelou CLI.

## Global flags

Available on any command:

| Flag               | Description                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `--json`           | Structured JSON output on stdout. Implies `--no-input`.                                       |
| `--agent`          | Agent mode: implies `--json`, `--no-input`, `--compact`, `NO_COLOR=1`, `JELOU_NO_SPINNERS=1`. |
| `--compact`        | JSON without whitespace (saves \~30-40% of tokens).                                           |
| `--human`          | Forces human-readable output even if stdout is redirected (overrides auto-JSON).              |
| `--no-input`       | Disables interactive prompts; destructive operations fail hard instead of asking.             |
| `--profile <name>` | Uses a specific auth profile for that command.                                                |
| `--describe`       | Emits the command schema as JSON, without executing it.                                       |

## Output modes for agents

**Auto-JSON on redirect:** if stdout is not a terminal (e.g. `jelou whoami |
jq`), the CLI switches to JSON automatically. Force it to human-readable with `--human` or
`JELOU_FORCE_HUMAN_OUTPUT=1`.

**Response shape:**

```json theme={null}
// Success
{ "ok": true, "data": { } }
// Error
{ "ok": false, "error": { "code": "...", "message": "...", "details": {} } }
```

Error codes: `AUTH_ERROR`, `FORBIDDEN`, `NOT_FOUND`, `VALIDATION_ERROR`,
`API_ERROR`, `MISSING_FUNCTIONS_PROJECT`, `MISSING_WORKFLOW_PROJECT`,
`MISSING_AUTH`, `INPUT_ERROR`, `UNKNOWN_ERROR`, `NETWORK_ERROR`,
`TRANSIENT_ERROR`, `MISSING_LOCKFILE`.

The `error` object can also include a `retryable` boolean field indicating
whether it's worth retrying the command as-is, with nothing changed:

```json theme={null}
{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Not found.", "retryable": false } }
```

The `--json` responses of action commands include a `breadcrumbs` array
with the suggested next commands. Streaming logs emit NDJSON (one
JSON object per line).

<Warning>
  Mode flags are **output-only**, never security. Collision
  preservation, the `push` rejection on unresolved incoming, schema
  validation, and dirty-state checks always run, with or without `--agent`. Destructive
  operations require `--yes` in JSON/agent mode — and that flag is
  for CI, not a shortcut to skip confirmations.
</Warning>

## Introspection with `--describe`

`--describe` walks the command tree and emits its signature as JSON, without
executing anything. It's read-only — use it to plan.

```bash theme={null}
jelou --describe                       # root command: lists top-level subcommands
jelou project --describe               # project subcommands
jelou databases create --describe      # arguments and options of a command
```

It returns `{ command, description, arguments, options, examples, subcommands }`.
Global flags are filtered out so you only see the command-specific
surface.

## Exit codes

The CLI uses granular exit codes so an agent can branch without parsing
stderr:

| Code | Meaning                    | Typical cause                                                               |
| ---- | -------------------------- | --------------------------------------------------------------------------- |
| 0    | Success                    | —                                                                           |
| 1    | Generic / unknown          | Build failures, uncategorized errors                                        |
| 2    | Input / validation         | Invalid flag, missing argument, schema mismatch                             |
| 3    | Not found                  | Unknown id, slug, or name                                                   |
| 4    | Auth / forbidden           | Missing or expired token, insufficient scope                                |
| 5    | DB not ready               | Database still provisioning                                                 |
| 6    | Transient / API            | 5xx, network timeout — safe to retry                                        |
| 7    | State conflict             | Lockfile drift, unresolved incoming, partial push                           |
| 8    | Secret detected (reserved) | The secret-scan helper exists but isn't wired into production paths yet     |
| 9    | Lock busy                  | Another `jelou pull`/`push` in progress                                     |
| 10   | Local schema mismatch      | The `qa.db` schema is incompatible (`QA_SCHEMA_MISMATCH`) — upgrade `jelou` |

Codes 7-9 are specific to `jelou pull`/`push`/`incoming` (8 is reserved and
not yet emitted on production paths). Code 10 shows up when the local
toolchain has fallen behind the schema the CLI expects. In `--json` mode, the
same code appears in `error.code` with a `hint` field that suggests the next
command.

## Environment variables

| Variable                   | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `JELOU_TOKEN`              | Authentication token (highest priority; no need for `jelou login`) |
| `JELOU_PROFILE`            | Default profile                                                    |
| `JELOU_NO_INPUT`           | `1` for non-interactive mode                                       |
| `JELOU_FORCE_HUMAN_OUTPUT` | `1` to force human-readable output even if stdout is redirected    |
| `NO_COLOR`                 | `1` to disable ANSI colors                                         |
| `JELOU_NO_SPINNERS`        | `1` to disable progress spinners (implied by `--agent`)            |
| `CI`                       | Auto-detected for non-interactive mode                             |

## Maintenance commands

```bash theme={null}
jelou update --agent     # is there a new version? (read-only)
jelou doctor --json      # health check (api, auth, profile, lockfile, project, authoring, skills, version)
jelou changelog          # release notes
jelou feedback           # send a report (always asks first)
```

To update the CLI:

```bash theme={null}
npm install -g @jelou/cli@latest
jelou --version
jelou agent install --global --all-targets --yes --no-input   # refreshes the skills
```

<Tip>
  To query company analytics (the catalog, one metric, or a whole dashboard),
  use `jelou metrics` — it has its own page in [Metrics](/en/guides/cli/metrics).
</Tip>