# CLI Reference

> Lookup reference for global options, environment variables, configuration resolution, profiles, exit codes, and common error troubleshooting.

Source: https://www.lev.com/docs/build/cli-reference

Last updated: May 2026

---
## Global Options

These flags work on every command. Place them before the command name.

| Flag | Short | Description |
|------|-------|-------------|
| `--profile NAME` | `-p` | Use a named profile (default: `default`) |
| `--output FORMAT` | `-o` | Output format: `auto` (default), `table`, `json`, `csv`. With `auto`, JSON is selected when output is piped (e.g. by an LLM agent) and a table is used otherwise |
| `--quiet` | `-q` | Minimal output — IDs only. Useful for agents chaining commands |
| `--verbose` | `-v` | Debug logging (request IDs, timing) |
| `--yes` | `-y` | Skip confirmation prompts |
| `--dry-run` | | Show what a mutation would do without executing. Recommended for agent-initiated writes before human approval |
| `--no-color` | | Disable terminal colors |
| `--version` | | Show CLI version |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `LEV_API_KEY` | API key for authentication | — |
| `LEV_API_URL` | API base URL | `https://api.lev.com` |
| `LEV_PROFILE` | Active profile name | `default` |
| `LEV_OUTPUT` | Default output format | auto-detect |
| `LEV_API_TIMEOUT` | Request timeout in seconds | `30` |
| `LEV_CA_BUNDLE` | Custom CA cert path for corporate proxies | — |
| `LEV_DEBUG_LOG` | File path for structured debug log output | — |
| `LEV_ORIGIN_APP` | Value for the `X-Origin-App` header on every request (analytics tag) | — |
| `LEV_ACTIVE_ACCOUNT` | Default account slug to scope requests to when the authenticated user belongs to multiple accounts | — |
| `NO_COLOR` | Standard env var — presence disables ANSI colors. Equivalent to `--no-color` | — |

## Configuration

Settings resolve in priority order:

**Configuration resolution priority**

- **1 (highest) — CLI flags:** --output json, --profile staging
- **2 — Environment variables:** LEV_API_KEY, LEV_OUTPUT
- **3 — Project config:** .lev.toml in the current repo root
- **4 — User config:** ~/.config/lev/config.toml
- **5 (lowest) — Defaults:** Table output, 30-second timeout

View the resolved configuration for the current context:

```bash
lev config show
```

## Profiles

Named profiles let you switch between environments or accounts without re-authenticating.

```bash
# Create a profile
lev auth login --profile staging

# Use a profile for a single command
lev -p staging deals list

# Switch the default profile
lev auth switch staging
```

Each profile stores its own API URL and keychain credential. Profile names are arbitrary strings.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Usage error (bad args, missing `--yes` when piped) |
| 3 | Authentication failed |
| 4 | Insufficient permissions (scope) |
| 5 | Resource not found |
| 6 | Validation error (bad input) |
| 7 | Rate limited |
| 8 | Server error |
| 9 | Network error (connection failed, timeout) |
| 130 | Interrupted (Ctrl+C) |

See **[CLI Workflows](/build/cli-workflows#error-handling-in-scripts)** for patterns that branch on these codes.

## Troubleshooting

**Common CLI errors**

- **No API key found:** No key in keychain or environment. Fix: run lev auth login or set LEV_API_KEY.
- **Authentication failed:** Key revoked or invalid. Fix: create a new key with lev api-keys create.
- **Permission denied:** Key lacks required scope. Fix: check scopes with lev auth status.
- **Rate limit reached:** Tier limit hit. Fix: wait and retry, or upgrade your tier.
- **Cannot reach Lev API:** Network or URL issue. Fix: check lev config show for the resolved URL.
- **Received non-JSON response:** Captive portal or proxy. Fix: check network; set LEV_CA_BUNDLE for proxy cert.
- **Write operation requires --yes:** Mutation detected in non-interactive context. Fix: add --yes flag or use --dry-run to preview.