Command Reference - Outlit Docs

Most commands in this reference share these common flags:

Flag	Description
`--api-key <key>`	Override the active API key for this request
`--json`	Force JSON output (auto-enabled when piped)
`--help`	Show help for the command

Customers List

List and filter customers with pagination.

outlit customers list [flags]

Flags

Flag	Type	Default	Description
`--billing-status`	string	—	Filter by billing status: `NONE`, `TRIALING`, `PAYING`, `PAST_DUE`, `CHURNED`
`--mrr-above`	number	—	MRR floor in cents (e.g. `10000` for $100/mo)
`--mrr-below`	number	—	MRR ceiling in cents
`--no-activity-in`	string	—	Inactive for period: `7d`, `14d`, `30d`, `90d`
`--has-activity-in`	string	—	Active within period: `7d`, `14d`, `30d`, `90d`
`--trait`	string	—	Exact trait filters as comma-separated `key=value` pairs (for example `segment=enterprise,active=true`)
`--search`	string	—	Search by name or domain
`--order-by`	string	`last_activity_at`	Sort field
`--order-direction`	string	`desc`	Sort direction: `asc`, `desc`
`--limit`	number	`20`	Results per page (1–100)
`--cursor`	string	—	Pagination cursor from a previous response

Examples

# Paying customers inactive for 30 days
outlit customers list --billing-status PAYING --no-activity-in 30d

# High-MRR customers sorted by revenue
outlit customers list --mrr-above 50000 --order-by mrr_cents --order-direction desc

# Search for a customer
outlit customers list --search "acme"

# Filter by exact customer traits
outlit customers list --trait "segment=enterprise,active=true"

# Pipe to jq
outlit customers list --json | jq '.items[] | {domain, mrr: .currentMrr}'

JSON Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "domain": "acme.com",
      "billingStatus": "PAYING",
      "currentMrr": 500000,
      "lastActivityAt": "2025-02-10T15:30:00Z",
      "status": "ACTIVE",
      "type": "COMPANY"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cursor_abc123",
    "total": 150
  }
}

Pagination

Use --cursor to page through results:

# First page
outlit customers list --limit 50 --json > page1.json

# Next page
CURSOR=$(jq -r '.pagination.nextCursor' page1.json)
outlit customers list --limit 50 --cursor "$CURSOR" --json

In interactive mode, the CLI shows a hint after the table:

Showing 20 of 150 total. Next page: --cursor cursor_abc123

Customers Get

Get a detailed customer profile with optional sections.

outlit customers get <customer> [flags]

Arguments

Argument	Required	Description
`customer`	Yes	Customer domain (e.g. `acme.com`), UUID, or name

Flags

Flag	Type	Default	Description
`--include`	string	—	Comma-separated sections: `users`, `revenue`, `recentTimeline`, `behaviorMetrics`
`--timeframe`	string	`30d`	Lookback window for included sections: `7d`, `14d`, `30d`, `90d`

Examples

# Basic profile
outlit customers get acme.com

# Full profile with all sections
outlit customers get acme.com --include users,revenue,recentTimeline --timeframe 90d

# By UUID
outlit customers get 550e8400-e29b-41d4-a716-446655440000

JSON Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Corp",
  "domain": "acme.com",
  "billingStatus": "PAYING",
  "currentMrr": 500000,
  "contacts": [
    {
      "id": "user-uuid",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "journeyStage": "ENGAGED"
    }
  ],
  "revenue": {
    "currentMrr": 500000,
    "historicalMrr": []
  },
  "recentTimeline": [
    {
      "type": "PAGE_VIEW",
      "channel": "SDK",
      "occurredAt": "2025-02-10T15:30:00Z"
    }
  ]
}

The --include users flag maps to the contacts key in the response, which contains user/contact data for that customer.

Customers Timeline

View the activity timeline for a customer, filtered by channel and event type.

outlit customers timeline <customer> [flags]

Arguments

Argument	Required	Description
`customer`	Yes	Customer domain or UUID

Flags

Flag	Type	Default	Description
`--timeframe`	string	`30d`	Lookback window: `7d`, `14d`, `30d`, `90d`
`--start-date`	string	—	Start datetime (ISO 8601, for example `2025-01-01T00:00:00Z`) — overrides `--timeframe`
`--end-date`	string	—	End datetime (ISO 8601, for example `2025-03-01T23:59:59Z`) — overrides `--timeframe`
`--channels`	string	—	Comma-separated channels: `SDK`, `EMAIL`, `SLACK`, `CALL`, `CRM`, `BILLING`, `SUPPORT`, `INTERNAL`
`--event-types`	string	—	Comma-separated types: `PAGE_VIEW`, `MEETING`, `SUPPORT_TICKET`, etc.
`--limit`	number	`20`	Results per page (1–100)
`--cursor`	string	—	Pagination cursor

When --start-date or --end-date is provided, --timeframe is ignored.

Examples

# Last 30 days (default)
outlit customers timeline acme.com

# Last 90 days, email and Slack only
outlit customers timeline acme.com --timeframe 90d --channels EMAIL,SLACK

# Custom date range
outlit customers timeline acme.com --start-date 2025-01-01T00:00:00Z --end-date 2025-03-01T23:59:59Z

# Page views and meetings only
outlit customers timeline acme.com --event-types PAGE_VIEW,MEETING --limit 50

JSON Response

{
  "items": [
    {
      "id": "event-uuid",
      "customerId": "customer-uuid",
      "type": "PAGE_VIEW",
      "channel": "SDK",
      "occurredAt": "2025-02-10T15:30:00Z",
      "metadata": {
        "url": "https://acme.com/pricing",
        "title": "Pricing Page"
      }
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "total": 45
  }
}

Users List

List and filter users across your customer base.

outlit users list [flags]

Flags

Flag	Type	Default	Description
`--journey-stage`	string	—	Filter by stage: `DISCOVERED`, `SIGNED_UP`, `ACTIVATED`, `ENGAGED`, `INACTIVE`
`--customer-id`	string	—	Filter to users of a specific customer (UUID)
`--no-activity-in`	string	—	Inactive for period: `7d`, `14d`, `30d`, `90d`
`--has-activity-in`	string	—	Active within period: `7d`, `14d`, `30d`, `90d`
`--trait`	string	—	Exact trait filters as comma-separated `key=value` pairs (for example `role=admin,onboarded=true`)
`--search`	string	—	Search by name or email
`--order-by`	string	`last_activity_at`	Sort field
`--order-direction`	string	`desc`	Sort direction: `asc`, `desc`
`--limit`	number	`20`	Results per page (1–100)
`--cursor`	string	—	Pagination cursor

Examples

# Find engaged users
outlit users list --journey-stage ENGAGED

# Inactive users from a specific customer
outlit users list --customer-id 550e8400-... --no-activity-in 30d

# Filter by exact user traits
outlit users list --trait "role=admin,onboarded=true"

# Search by name
outlit users list --search "alice" --order-by last_activity_at

JSON Response

{
  "items": [
    {
      "id": "user-uuid",
      "email": "jane@acme.com",
      "name": "Jane Doe",
      "customerId": "customer-uuid",
      "journeyStage": "ENGAGED",
      "lastActivityAt": "2025-02-10T15:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "cursor_abc",
    "total": 500
  }
}

Facts

Retrieve AI-generated facts, signals, and insights for a customer.

outlit facts list <customer> [flags]
outlit facts get --fact-id <id> [flags]

`facts list` Arguments

Argument	Required	Description
`customer`	Yes	Customer domain or UUID

`facts list` Flags

Flag	Type	Default	Description
`--status`	string	—	Comma-separated fact status filter: `ACTIVE`, `ACKNOWLEDGED`, `RESOLVED`, `SNOOZED`, `CANDIDATE`
`--source-types`	string	—	Comma-separated generic source type filter: `EMAIL`, `CALL`, `CALENDAR_EVENT`, `SUPPORT_TICKET`, `OPPORTUNITY`. Case-insensitive. Aliases: `CRM`, `CRM_OPPORTUNITY`
`--fact-types`	string	—	Comma-separated customer-memory fact type filter: e.g. `CHURN_RISK`, `EXPANSION`, `SENTIMENT`, `PRODUCT_USAGE`
`--fact-categories`	string	—	Comma-separated fact category filter: `MEMORY`, `CUSTOM`
`--after`	string	—	Lower bound on fact occurrence time (ISO 8601 datetime)
`--before`	string	—	Upper bound on fact occurrence time (ISO 8601 datetime)
`--limit`	number	`20`	Results per page (1–100)
`--cursor`	string	—	Pagination cursor

`facts get` Flags

Flag	Type	Default	Description
`--fact-id`	string	—	Exact fact identifier
`--include`	string	—	Comma-separated best-effort expansions. `evidence` requests evidence details when available

Examples

# All facts for a customer
outlit facts list acme.com

# Filter by status and source type
outlit facts list acme.com --status ACTIVE --source-types CALL,OPPORTUNITY --after 2025-01-01T00:00:00Z

# Filter customer-memory facts by public fact type
outlit facts list acme.com --fact-types CHURN_RISK,PRODUCT_USAGE

# Pipe for processing
outlit facts list acme.com --json | jq '.facts[] | select(.severity == "HIGH")'

# Fetch one exact fact with best-effort evidence expansion
outlit facts get --fact-id fact_123 --include evidence

JSON Response

{
  "customer": {
    "id": "cust_123",
    "name": "Acme",
    "domain": "acme.com"
  },
  "facts": [
    {
      "id": "fact-uuid",
      "assertion": "Budget concerns raised",
      "factType": "BUDGET",
      "factCategory": "MEMORY",
      "status": "ACTIVE",
      "confidence": 0.92,
      "severity": "HIGH",
      "occurredAt": "2025-02-10T14:00:00Z",
      "detectedAt": "2025-02-10T15:30:00Z",
      "linkedSourceRef": {
        "sourceType": "CALL",
        "sourceId": "call_123",
        "occurredAt": "2025-02-10T14:00:00Z",
        "permalink": "https://granola.ai/notes/call_123"
      },
      "sourceMetadata": {
        "sourceType": "CALL",
        "sourceId": "call_123",
        "sourceOccurredAt": "2025-02-10T14:00:00Z",
        "sourceQuote": "Budget is blocked until next quarter.",
        "permalink": "https://granola.ai/notes/call_123"
      }
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  }
}

facts get returns the same canonical fact shape as facts list. Passing --include evidence requests a best-effort evidence expansion; unsupported include values are ignored.

Search

Semantic search across customer context. Results are grouped at the artifact level, so matching sources and facts are returned directly instead of raw chunks.

outlit search <query> [flags]

Arguments

Argument	Required	Description
`query`	Yes	Natural language search query

Flags

Flag	Type	Default	Description
`--customer`	string	—	Scope to a specific customer (domain or UUID)
`--top-k`	number	`20`	Maximum results to return (1–50)
`--after`	string	—	Filter to events after this ISO 8601 datetime
`--before`	string	—	Filter to events before this ISO 8601 datetime
`--source-types`	string	—	Comma-separated generic source type filter (`EMAIL`, `CALL`, `CALENDAR_EVENT`, `SUPPORT_TICKET`, `OPPORTUNITY`). Case-insensitive. Aliases: `CRM`, `CRM_OPPORTUNITY`

Examples

# Organization-wide search
outlit search "pricing objections"

# Scoped to a customer
outlit search "budget concerns" --customer acme.com

# Time-bounded
outlit search "expansion signals" --after 2025-01-01T00:00:00Z --before 2025-03-31T23:59:59Z

# Filter by source type
outlit search "renewal opportunities" --source-types CALL,OPPORTUNITY

# More results (max 50)
outlit search "churn risk" --top-k 50 --json

JSON Response

{
  "customer": {
    "id": "cust_123",
    "name": "Acme",
    "domain": "acme.com"
  },
  "results": [
    {
      "kind": "source",
      "score": 0.92,
      "matchCount": 2,
      "sourceType": "CALL",
      "sourceId": "call_456",
      "occurredAt": "2025-02-10T15:30:00Z",
      "matches": [
        {
          "text": "Customer mentioned pricing concerns in Q1 planning meeting"
        }
      ]
    }
  ]
}

Search returns both matching source and fact artifacts when both are relevant. Multiple chunk hits from the same source are grouped into one source result.

Sources

Fetch one exact source by generic sourceType and sourceId.

outlit sources get --source-type <type> --source-id <id>

Flags

Flag	Type	Default	Description
`--source-type`	string	—	Source type: `EMAIL`, `CALL`, `CALENDAR_EVENT`, `SUPPORT_TICKET`, `OPPORTUNITY`. Case-insensitive. Aliases: `CRM`, `CRM_OPPORTUNITY`
`--source-id`	string	—	Exact source identifier

Examples

outlit sources get --source-type CALL --source-id call_123
outlit sources get --source-type OPPORTUNITY --source-id opp_123
outlit sources get --source-type SUPPORT_TICKET --source-id ticket_456 --json

Notify

Send a notification to the organization’s configured default notifier. Slack is the default notifier when no destination is supplied.

outlit notify --title <title> <payload> [flags]
outlit notify --title <title> --payload-file <path> [flags]
outlit notify --title <title> --markdown <markdown> [flags]

Arguments

Argument	Required	Description
`payload`	No*	Notification payload as JSON or a raw string. Any JSON-serializable object, array, scalar, or string is accepted. Provide a payload, `--payload-file`, `--markdown`, or `--markdown-file`.

Flags

Flag	Type	Default	Description
`--title`	string	—	Notification title
`--payload-file`	string	—	Path to a payload file. Takes precedence over the positional payload.
`--markdown`	string	—	Markdown notification body
`--markdown-file`	string	—	Path to a markdown file. Takes precedence over `--markdown`.
`--message`	string	—	Optional summary message
`--severity`	string	—	Optional severity: `low`, `medium`, `high`
`--source`	string	—	Optional source label
`--subject`	string	—	Optional subject line
`--destination`	string	—	Optional comma-separated destinations in `provider[:channelId]` form. Supported provider: `slack`.

Examples

# Markdown body
outlit notify --title "Expansion signal" --markdown "**Expansion signal**\n\n- Customer: acme.com"

# Inline JSON payload
outlit notify --title "Expansion signal" '{"customer":"acme.com","score":0.91}'

# Raw string payload
outlit notify --title "Escalation" "Check this account before renewal"

# Payload from a file
outlit notify --title "Usage decay" --payload-file ./payload.json

# Explicit Slack destination
outlit notify --title "Escalation" --markdown "**Check this account**" --destination slack:C123

# High-severity notification with a message
outlit notify --title "Escalation" --severity high --message "Check this account" '{"customer":"acme.com"}'

Provide --markdown, --markdown-file, a positional payload, or --payload-file. When both payload forms are provided, --payload-file takes precedence. When both markdown forms are provided, --markdown-file takes precedence.

SQL

Execute read-only SQL queries against Outlit analytics views.

outlit sql <query> [flags]
outlit sql --query-file <path> [flags]

Arguments

Argument	Required	Description
`query`	Yes*	SQL query string (*or use `--query-file`)

Flags

Flag	Type	Default	Description
`--query-file`	string	—	Path to a `.sql` file (takes precedence over positional arg)
`--limit`	number	`1000`	Maximum rows to return

Examples

# Inline query
outlit sql "SELECT event_type, COUNT(*) as cnt FROM activity GROUP BY 1 ORDER BY cnt DESC"

# From a file
outlit sql --query-file ./queries/monthly-activity.sql

# Pipe to jq
outlit sql "SELECT domain, mrr_cents FROM customers ORDER BY mrr_cents DESC LIMIT 10" | jq

JSON Response

{
  "rows": [
    { "event_type": "PAGE_VIEW", "cnt": 12500 },
    { "event_type": "MEETING", "cnt": 340 }
  ],
  "rowCount": 2
}

Available Views

Use outlit schema to discover all views and their columns. Common views:

View	Description
`activity`	Event stream (page views, meetings, emails, etc.)
`customers`	Denormalized customer attributes and metrics
`users`	Denormalized user attributes
`revenue`	Monthly recurring revenue snapshots

Schema

Discover analytics views and their column definitions.

outlit schema [view]

Arguments

Argument	Required	Description
`view`	No	Specific view name — omit to list all views

Examples

# List all views
outlit schema

# Describe a specific view
outlit schema activity

# JSON output
outlit schema customers --json

JSON Response

{
  "tables": [
    {
      "name": "activity",
      "columns": [
        { "name": "id", "type": "uuid", "nullable": false },
        { "name": "event_type", "type": "varchar", "nullable": false }
      ]
    }
  ]
}

​Customers List

​Flags

​Examples

​JSON Response

​Pagination

​Customers Get

​Arguments

​Flags

​Examples

​JSON Response

​Customers Timeline

​Arguments

​Flags

​Examples

​JSON Response

​Users List

​Flags

​Examples

​JSON Response

​Facts

​facts list Arguments

​facts list Flags

​facts get Flags

​Examples

​JSON Response

​Search

​Arguments

​Flags

​Examples

​JSON Response

​Sources

​Flags

​Examples

​Notify

​Arguments

​Flags

​Examples

​SQL

​Arguments

​Flags

​Examples

​JSON Response

​Available Views

​Schema

​Arguments

​Examples

​JSON Response

Customers List

Flags

Examples

JSON Response

Pagination

Customers Get

Arguments

Flags

Examples

JSON Response

Customers Timeline

Arguments

Flags

Examples

JSON Response

Users List

Flags

Examples

JSON Response

Facts

`facts list` Arguments

`facts list` Flags

`facts get` Flags

Examples

JSON Response

Search

Arguments

Flags

Examples

JSON Response

Sources

Flags

Examples

Notify

Arguments

Flags

Examples

SQL

Arguments

Flags

Examples

JSON Response

Available Views

Schema

Arguments

Examples

JSON Response