Configuration

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:

{
  "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.

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:

Bash
Zsh
Fish

outlit completions bash >> ~/.bash_completion
source ~/.bash_completion

outlit completions zsh >> ~/.zshrc
exec zsh

outlit completions fish > ~/.config/fish/completions/outlit.fish

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:

{
  "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:

{
  "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

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

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):

{
  "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.

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), 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

#!/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

outlit customers list --limit 100 --json \
  | jq -r '.items[] | [.domain, .billingStatus, .currentMrr] | @csv'

CI health check

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

Filter inactive users

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

Agents

CLI

Concepts

Outlit SDKs

Examples

Environment variables

Config directory

Files

Update checks

Shell completions

Output behavior

TTY mode (interactive)

JSON mode

When JSON mode activates

Error handling

Error codes

Data formatting

Relative date format

Scripting examples

Export all customers

Export to CSV

CI health check

Filter inactive users

​Environment variables

​Config directory

​Files

​Update checks

​Shell completions

​Output behavior

​TTY mode (interactive)

​JSON mode

​When JSON mode activates

​Error handling

​Error codes

​Data formatting

​Relative date format

​Scripting examples

​Export all customers

​Export to CSV

​CI health check

​Filter inactive users

Environment variables

Config directory

Files

Update checks

Shell completions

Output behavior

TTY mode (interactive)

JSON mode

When JSON mode activates

Error handling

Error codes

Data formatting

Relative date format

Scripting examples

Export all customers

Export to CSV

CI health check

Filter inactive users