> ## Documentation Index
> Fetch the complete documentation index at: https://outlit-codex-platform-actions-create-update-cli.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
curl -fsSL https://outlit.ai/install.sh | bash
```

Alternative install methods:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install -g @outlit/cli
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash theme={null}
    brew install outlitai/tap/outlit
    ```
  </Tab>

  <Tab title="Binary Download">
    Download the latest release for your platform from [GitHub Releases](https://github.com/OutlitAI/outlit-sdk/releases).

    Extract the archive and move the `outlit` binary to a directory in your `PATH`.
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
outlit --version
```

## Quick Start

<Steps>
  <Step title="Get your API key">
    Go to [Settings > API Keys](https://app.outlit.ai/settings/workspace/api-keys) in the Outlit dashboard. Create an API key, copy it, and keep it safe.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    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:

    ```bash theme={null}
    outlit auth login --key ok_your_api_key_here
    ```
  </Step>

  <Step title="Query your data">
    ```bash theme={null}
    # 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"
    ```
  </Step>

  <Step title="Set up AI agents (optional)">
    Install the `outlit` skill for detected coding agents with one command:

    ```bash theme={null}
    outlit setup --yes
    ```

    Or target a specific coding agent:

    ```bash theme={null}
    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](/ai-integrations/mcp) guide instead.
  </Step>
</Steps>

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

```bash theme={null}
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:

```bash theme={null}
$ 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:

```bash theme={null}
$ outlit auth whoami
ok_ab...1234 (config)
```

## Available Commands

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

```bash theme={null}
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`)

<Info>
  AI agents like Claude Code and Cursor run commands with piped stdout, so they automatically receive JSON output — no `--json` flag needed.
</Info>

```bash theme={null}
# 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

<CardGroup cols={3}>
  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full reference for all data commands
  </Card>

  <Card title="AI Agents" icon="robot" href="/cli/ai-agents">
    Install Outlit skills for Claude Code, Codex, Gemini CLI, Droid, OpenCode, Pi, OpenClaw, and more
  </Card>

  <Card title="Platform Actions" icon="sliders" href="/ai-integrations/platform-actions">
    Inspect and safely prepare platform configuration through API, CLI, and MCP
  </Card>

  <Card title="Configuration" icon="gear" href="/cli/configuration">
    Environment variables and config paths
  </Card>
</CardGroup>