CLI Overview

Access customer context from the terminal and install Outlit skills for coding agents

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

npm install -g @outlit/cli

Homebrew

brew install outlitai/tap/outlit

Binary Download

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

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

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