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

> ## Agent Instructions
> Outlit is the product that monitors customers and completes approved customer work. The customer context interfaces are the API, CLI, MCP server, and skills. Canonical references on this site: /api-reference/introduction for API concepts and authentication, /openapi.json for the public API contract, /cli/overview for the CLI, /ai-integrations/mcp for MCP. Prefer the `outlit` CLI or MCP tools for agent tasks; cite page sources when answering.

# Configuration

> Environment variables, output behavior, and file paths for the Outlit CLI.

## Environment variables

| Variable | Description | Default |
| - | - | - |
| `OUTLIT_API_KEY` | API key for authentication (overridden by `--api-key` flag) | — |
| `OUTLIT_NO_UPDATE_NOTIFIER` | Disable automatic interactive CLI update notices when set | — |
| `XDG_CONFIG_HOME` | Override the config directory (Unix) | `~/.config` |
| `CI` | Triggers JSON output mode when equal to exactly `"true"` or `"1"` | — |
| `GITHUB_ACTIONS` | Triggers JSON output mode when set | — |
| `TERM` | When set to `dumb`, switches output to JSON | — |

## Config directory

The CLI stores configuration in a platform-specific directory:

| Platform | Path |
| - | - |
| macOS / Linux | `~/.config/outlit/` (or `$XDG_CONFIG_HOME/outlit/`) |
| Windows | `%APPDATA%\outlit\` |

### Files

| File | Purpose | Created by |
| - | - | - |
| `credentials.json` | Stored API key | `outlit auth login` |
| `update-check.json` | Cached latest CLI version and installer hint | Automatic update check |

The credentials file has `0600` permissions (readable by owner only) and contains:

```json theme={null}
{
  "apiKey": "ok_your_api_key_here"
}
```

## Update checks

In interactive terminals, the CLI periodically checks npm for the latest `@outlit/cli` version and caches the result in `update-check.json`. Cached notices are printed to stderr and never affect JSON output.

```bash theme={null}
OUTLIT_NO_UPDATE_NOTIFIER=1 outlit customers list
```

Use `outlit upgrade` to update with the same package manager that installed the CLI when it can be inferred.

## Shell completions

Generate completion scripts for your shell:

<Tabs>
  <Tab title="Bash">
    ```bash theme={null}
    outlit completions bash >> ~/.bash_completion
    source ~/.bash_completion
    ```
  </Tab>

  <Tab title="Zsh">
    ```bash theme={null}
    outlit completions zsh >> ~/.zshrc
    exec zsh
    ```
  </Tab>

  <Tab title="Fish">
    ```bash theme={null}
    outlit completions fish > ~/.config/fish/completions/outlit.fish
    ```
  </Tab>
</Tabs>

## Output behavior

### TTY mode (interactive)

When running in an interactive terminal, the CLI outputs:

* **Tables** with Unicode box-drawing characters for list commands
* **Spinners** on stderr during API calls
* **Colored output** with green checkmarks for success
* **Pagination hints** showing total count and next cursor

Example:

```
┌──────────────────────────┬────────────┬─────────┬──────────┬────────────┐
│ Name                     │ Domain     │ Billing │ MRR      │ Last Active│
├──────────────────────────┼────────────┼─────────┼──────────┼────────────┤
│ Acme Corp                │ acme.com   │ PAYING  │ $5000.00 │ 2d ago     │
│ Globex Inc               │ globex.com │ TRIALING│ $0.00    │ 5h ago     │
└──────────────────────────┴────────────┴─────────┴──────────┴────────────┘
Showing 20 of 150 total. Next page: --cursor cursor_abc123
```

### JSON mode

When JSON mode is active, all output is pretty-printed JSON on stdout:

```json theme={null}
{
  "items": [
    {
      "id": "cus_123",
      "name": "Acme Corp",
      "domain": "acme.com"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cursor_abc123",
    "total": 150
  }
}
```

Errors are also JSON, written to stderr:

```json theme={null}
{
  "error": "Not authenticated. Run `outlit auth login` or pass --api-key.",
  "code": "not_authenticated"
}
```

### When JSON mode activates

JSON mode activates automatically in any of these conditions:

| Condition | Example |
| - | - |
| `--json` flag | `outlit customers list --json` |
| stdout is piped | `outlit customers list \| jq` |
| `CI=true` or `CI=1` | GitHub Actions, CircleCI, etc. |
| `GITHUB_ACTIONS` is set | GitHub Actions |
| `TERM=dumb` | Terminals without ANSI support |

<Info>
  This means AI agents (Claude Code, Cursor, etc.) automatically get JSON output when they run CLI commands as subprocesses — no extra configuration needed.
</Info>

## Error handling

All errors exit with code `1`. The error format depends on the output mode:

**TTY:**

```
Error: Not authenticated. Run `outlit auth login` or pass --api-key.
```

**JSON (stderr):**

```json theme={null}
{
  "error": "Not authenticated. Run `outlit auth login` or pass --api-key.",
  "code": "not_authenticated"
}
```

### Error codes

| Code | Description |
| - | - |
| `not_authenticated` | No API key found in any source |
| `auth_required` | Client creation failed (authentication error) |
| `auth_request_failed` | Browser/device auth request failed |
| `auth_timeout` | Timed out waiting for browser authentication |
| `invalid_key_format` | API key doesn't match expected format (`ok_` prefix) |
| `invalid_key` | API key rejected by the server |
| `validation_failed` | Key failed server verification during `auth login` |
| `missing_key` | `--key` flag required but not provided (non-interactive `auth login`) |
| `missing_input` | Required argument not provided |
| `invalid_input` | Argument failed validation |
| `api_error` | API request failed (includes HTTP status) |
| `api_unavailable` | API unreachable (network/DNS failure) |
| `unsupported_core_version` | The workspace does not support this command yet |
| `file_error` | Failed reading or writing a file |
| `write_error` | Failed to write a config file |
| `unlink_error` | Failed to delete credentials file during `auth logout` |
| `unknown_agent` | `--agent` value isn't a supported agent alias |
| `unknown_provider` | Provider isn't a supported integration |
| `unknown_shell` | Shell isn't supported by `completions` |
| `agent_required` | Command requires `--agent` (non-interactive) |
| `runner_not_found` | Agent runtime binary not found on PATH |
| `skills_install_error` | Skill installation failed |
| `update_check_failed` | Version update check failed |
| `upgrade_failed` | Self-upgrade failed |

Commands that call Outlit can return the server’s `code`, `message`, `retryable`, and `requestId` fields. See [Error responses](/api-reference/tools#error-responses).

## Data formatting

The CLI formats values for readability in TTY mode:

| Type | Raw value | Displayed as |
| - | - | - |
| MRR | `500000` | `$5000.00` |
| Date | `2025-02-10T15:30:00Z` | `2d ago` |
| Long names | `Very Long Customer Name Inc` | `Very Long Custo...` |
| Missing values | `null` / `undefined` | `--` |

The MRR column always divides `currentMrr` by 100 and shows `$`, because the list result doesn't name the customer's currency. That is right for customers billed in USD. For EUR, GBP, and CAD the amount is right but the symbol isn't. Other currencies follow the billing provider's amount rules (see [Stripe's currency docs](https://docs.stripe.com/currencies)), so the amount can be wrong too: JPY has no minor unit, so `500000` is ¥500,000, not `$5000.00`. Use `--json` for the raw `currentMrr`.

### Relative date format

| Time elapsed | Display |
| - | - |
| Under 1 minute | `just now` |
| Under 1 hour | `5m ago` |
| Under 1 day | `3h ago` |
| Under 30 days | `7d ago` |
| Under 1 year | `2mo ago` |
| 1 year or more | `1y ago` |

## Scripting examples

### Export all customers

```bash theme={null}
#!/bin/bash
LIMIT=100
CURSOR=""

while true; do
  if [ -z "$CURSOR" ]; then
    PAGE=$(outlit customers list --limit $LIMIT --json)
  else
    PAGE=$(outlit customers list --limit $LIMIT --cursor "$CURSOR" --json)
  fi

  jq -r '.items[].domain' <<< "$PAGE" >> all_domains.txt

  HAS_MORE=$(jq -r '.pagination.hasMore' <<< "$PAGE")
  [ "$HAS_MORE" = "false" ] && break

  CURSOR=$(jq -r '.pagination.nextCursor' <<< "$PAGE")
done
```

### Export to CSV

```bash theme={null}
outlit customers list --limit 100 --json \
  | jq -r '.items[] | [.domain, .billingStatus, .currentMrr] | @csv'
```

### CI health check

```bash theme={null}
# Validate API key and agent setup in CI
outlit doctor --json | jq -e '.ok' > /dev/null || exit 1
```

### Filter inactive users

```bash theme={null}
outlit users list --journey-stage INACTIVE --no-activity-in 30d --json \
  | jq '.items[] | {email, customer: .customerId, lastSeen: .lastActivityAt}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.