CLI Overview

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
Homebrew
Binary Download

npm install -g @outlit/cli

brew install outlitai/tap/outlit

Download the latest release for your platform from GitHub Releases.Extract the archive and move the outlit binary to a directory in your PATH.

Verify the installation:

outlit --version

Quick Start

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.

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

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 activity GROUP BY 1"

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:

Priority	Source	How to set
1	`--api-key` flag	`outlit customers list --api-key ok_...`
2	`OUTLIT_API_KEY` env var	`export OUTLIT_API_KEY=ok_...`
3	Config file	`outlit 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

Command	Description
`customers list`	Filter and list customers by billing status, MRR, activity, and traits
`customers get`	Get a detailed customer profile with optional sections (users, revenue, etc.)
`customers timeline`	View activity timeline filtered by channel and event type
`users list`	Filter and list users by journey stage, activity, customer, and traits
`facts`	Retrieve AI-generated facts and signals for a customer
`search`	Natural language search across customer context
`sources get`	Retrieve one exact source record behind a fact or search result
`sql`	Run SQL queries against analytics views
`schema`	Discover analytics views and columns
`onboard`	Bootstrap auth, install an agent skill, and inspect integration readiness
`integrations list`	List available integrations and connection status
`integrations capabilities`	Show setup modes, required fields, and follow-up steps
`integrations setup`	Run browser-auth or direct-credential provider setup
`integrations status`	Show sync status for connected integrations
`agents list`	List configured hosted agents
`automations list`	List configured automations
`signals list`	List configured automation signals
`destinations list`	List configured automation destinations with masked configuration
`identity suggestions list`	List customer identity merge suggestions
`setup`	Install Outlit skills for coding agents
`doctor`	Run environment diagnostics
`completions`	Generate shell completion scripts
`upgrade`	Upgrade 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

Platform Actions

Inspect and safely prepare platform configuration through API, CLI, and MCP

Configuration

Environment variables and config paths

Getting Started

Concepts

Browser SDKs

Server SDKs

CLI

AI Integrations

Use Cases

Installation

Quick Start

Authentication

Auth Commands

Available Commands

Updates

Output Modes

What’s Next

Commands

AI Agents

Platform Actions

Configuration

​Installation

​Quick Start

​Authentication

​Auth Commands

​Available Commands

​Updates

​Output Modes

​What’s Next

Commands

AI Agents

Platform Actions

Configuration

Installation

Quick Start

Authentication

Auth Commands

Available Commands

Updates

Output Modes

What’s Next