Skip to main content
The Outlit CLI gives you direct access to structured customer context from the terminal. List customers, inspect activity timelines, search conversations and facts, run SQL queries, and install Outlit skills for coding agents without leaving your workflow.

​
Installation

Fastest path: 
curl -fsSL https://outlit.ai/install.sh | bash
Alternative install methods: 
npm install -g @outlit/cli
Verify the installation: 
outlit --version

​
Quick Start

1

Get your API key

Go to Settings > API Keys in the Outlit dashboard. Create an API key, copy it, and keep it safe.
Treat your API key like a password. It grants read access to your customer data. You can revoke keys at any time from the dashboard.
2

Authenticate

outlit auth login
The CLI will prompt you to enter your API key. It validates the key against the API and stores it securely at ~/.config/outlit/credentials.json with 0600 permissions.You can also pass the key directly:
outlit auth login --key ok_your_api_key_here
3

Query your data

# List paying customers
outlit customers list --billing-status PAYING

# Get a customer profile
outlit customers get acme.com --include users,revenue,recentTimeline

# Search with natural language
outlit search "pricing objections last quarter"

# Run SQL
outlit sql "SELECT event_type, COUNT(*) FROM events GROUP BY 1"
4

Set up AI agents (optional)

Install the outlit skill for detected coding agents with one command:
outlit setup --yes
Or target a specific coding agent:
outlit setup claude-code
outlit setup codex
outlit setup gemini
outlit setup droid
outlit setup opencode
outlit setup pi
outlit setup openclaw
For MCP clients like Cursor or VS Code, use the direct MCP Integration guide instead.

​
Authentication

The CLI resolves your API key from the following sources, in order:
PrioritySourceHow to set
1--api-key flagoutlit customers list --api-key ok_...
2OUTLIT_API_KEY env varexport OUTLIT_API_KEY=ok_...
3Config fileoutlit auth login

​
Auth Commands

outlit auth login           # Store API key (interactive or --key)
outlit auth logout          # Remove stored credentials
outlit auth signup          # Open sign-up page in browser
outlit auth status          # Check authentication state and validate key
outlit auth whoami          # Validate key and print masked key + source
auth status makes a live API call to validate your key: 
$ outlit auth status
✓ Authenticated
  Key:    ok_ab...1234
  Source: config
auth whoami validates your key and outputs a single line in TTY mode — useful for scripting: 
$ outlit auth whoami
ok_ab...1234 (config)

​
Available Commands

CommandDescription
customers listFilter and list customers by billing status, MRR, activity, and traits
customers getGet a detailed customer profile with optional sections (users, revenue, etc.)
customers timelineView activity timeline filtered by channel and event type
users listFilter and list users by journey stage, activity, customer, and traits
factsRetrieve AI-generated facts and signals for a customer
searchNatural language search across customer context
sources getRetrieve one exact source record behind a fact or search result
sqlRun SQL queries against analytics tables
schemaDiscover database tables and columns
integrations listList available integrations and connection status
integrations addConnect a new integration (OAuth or API key)
integrations removeDisconnect an integration and remove synced data
integrations statusShow sync status for connected integrations
setupInstall Outlit skills for coding agents
doctorRun environment diagnostics
completionsGenerate shell completion scripts
upgradeUpgrade the CLI with the package manager that installed it

​
Updates

In interactive terminals, the CLI checks for newer published versions using a local cache so normal commands stay fast. When an update is available, it prints a short notice to stderr and continues. 
outlit upgrade
outlit upgrade tries to use the same package manager that installed the CLI, such as Bun, npm, pnpm, or Yarn. Set OUTLIT_NO_UPDATE_NOTIFIER=1 to suppress automatic notices.

​
Output Modes

The CLI has two output modes: interactive (tables, spinners, colors) and JSON (machine-readable). JSON mode activates automatically when:
  • stdout is piped (outlit customers list | jq)
  • --json flag is passed
  • Running in CI (CI=true or GITHUB_ACTIONS is set)
  • Terminal is dumb (TERM=dumb)
AI agents like Claude Code and Cursor run commands with piped stdout, so they automatically receive JSON output — no --json flag needed.
# Interactive table
outlit customers list

# JSON output (explicit)
outlit customers list --json

# JSON output (automatic via pipe)
outlit customers list | jq '.items[].domain'

​
What’s Next

Commands

Full reference for all data commands

AI Agents

Install Outlit skills for Claude Code, Codex, Gemini CLI, Droid, OpenCode, Pi, OpenClaw, and more

Configuration

Environment variables and config paths