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

# Configuration

> Global flags, environment variables, output formats, and POSIX exit codes.

## Global flags

Every `ekso` command accepts these flags. They sit alongside command-specific options:

| Flag                    | Description                                                                                       | Env var        | Default |
| ----------------------- | ------------------------------------------------------------------------------------------------- | -------------- | ------- |
| `--url <URL>`           | Absolute URL of your Ekso install (e.g. `https://ekso.acme.com`). Required unless env-var is set. | `EKSO_URL`     | —       |
| `--api-key <KEY>`       | API key for non-interactive auth. Overrides any stored device-flow tokens.                        | `EKSO_API_KEY` | —       |
| `-f, --format <FORMAT>` | Output format. One of `json`, `jsonl`, `yaml`, `table`.                                           | `EKSO_FORMAT`  | `json`  |
| `-q, --quiet`           | Suppress non-essential output. On `create`, prints just the new id.                               | —              | off     |
| `-v, --verbose`         | Verbose logging — request/response details.                                                       | —              | off     |
| `--no-color`            | Disable ANSI colors. Honours [NO\_COLOR](https://no-color.org).                                   | `NO_COLOR`     | off     |
| `--timeout <SECONDS>`   | HTTP timeout in seconds.                                                                          | `EKSO_TIMEOUT` | `30`    |

Flags always win over env vars. Env vars are convenient for shell sessions and CI runners — set once, every subsequent `ekso ...` call inherits them.

Self-host: there is no concept of tenant subdomain. The install URL — whatever `PublicUrl` you set during the `/startup` wizard — is the single addressable identity, and the CLI talks to it directly.

## Recommended shell setup

Drop these in your `.zshrc` / `.bashrc` so you don't repeat yourself:

```bash theme={null}
# Production install
export EKSO_URL=https://ekso.acme.com
# CI/agent — leave unset for local dev (uses cached device-flow tokens)
# export EKSO_API_KEY=ek_live_xxx
```

For local backend development:

```bash theme={null}
export EKSO_URL=https://devinc.localhost:7070
```

## Output formats

The CLI defaults to **JSON** — the same shape Ekso returns over HTTP. Use `--format` (or `EKSO_FORMAT`) to change:

| Format           | Use case                                                           |
| ---------------- | ------------------------------------------------------------------ |
| `json` (default) | Machine-readable, pipes cleanly into `jq`.                         |
| `jsonl`          | Newline-delimited JSON. One record per line. Good for streaming.   |
| `yaml`           | Human-readable for browsing, terraform-style configs.              |
| `table`          | Compact aligned columns for terminal viewing. Loses nested fields. |

```bash theme={null}
ekso item list --format table
```

`-q, --quiet` is independent of `--format` — it suppresses success messages and non-essential prose, leaving only the data (or just the id, on create). Combine `-q --format json` for clean machine output.

## Exit codes

The CLI follows POSIX conventions plus a few Ekso-specific codes:

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success                                                         |
| `1`  | Generic error (unknown failure)                                 |
| `2`  | Usage error (bad flags / missing required argument)             |
| `3`  | Auth error (no credentials, expired refresh token, revoked key) |
| `4`  | Forbidden (insufficient permissions, e.g. not a super admin)    |
| `5`  | Not found (HTTP 404)                                            |
| `6`  | Validation error (HTTP 400 / 422)                               |
| `7`  | Rate limited (HTTP 429) — back off and retry                    |
| `8`  | Network error (DNS, TCP, TLS, timeout) — typically transient    |
| `9`  | Server error (HTTP 5xx)                                         |

Branch on these in shell pipelines:

```bash theme={null}
ekso item create --name "Bug" --url https://ekso.acme.com
case $? in
    0) echo "ok" ;;
    3) echo "re-authenticate" ; ekso auth login --url https://ekso.acme.com ;;
    7) echo "rate limited" ; sleep 30 ;;
    *) echo "failed: exit $?" ;;
esac
```

## Help

Every command and branch has built-in help:

```bash theme={null}
ekso --help                  # Top-level: list of branches
ekso item --help             # Branch: list of verbs
ekso item create --help      # Verb: flags + arguments
```

`--help` prints the same surface as the docs but reflects the binary you have installed — it's the source of truth if the rendered docs and the installed CLI ever drift.