# Outlit > Use when accessing Outlit customer intelligence through the `outlit` CLI, Outlit MCP tools, Pi tools, or @outlit/tools, including customer lookups, users, workspace users, timelines, facts, source evidence, semantic search, revenue, churn, SQL analytics, setup, integrations, or troubleshooting agent access. - Skill: `outlitai/outlit` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add outlitai/outlit` - Raw SKILL.md: https://api.skillmd.com/api/skills/outlitai/outlit/raw - Safety review: WARNING (external: skill-scanner WARNING, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: OutlitAI (https://skillmd.com/u/outlitai) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/outlitai/outlit --- # Outlit Outlit joins product activity, conversations, billing, support, CRM, and web signals into customer profiles, timelines, facts, and source evidence for agents. ## When to Use Outlit Use Outlit when the user needs real customer context for onboarding, adoption, retention, renewal, or expansion. Typical jobs include: - Find accounts with declining activity, renewal risk, expansion demand, or stalled onboarding. - Explain what changed for a customer and trace the answer to facts, events, conversations, or source records. - Prepare account research, customer-success follow-up, or custom analytics across customer data. - Inspect or configure an Outlit workspace capability when the user explicitly asks. Do not call Outlit for generic customer-success advice that does not need workspace data. Use the `outlit-sdk` skill instead when the user wants to instrument an application with tracking SDKs. ## Choose the Interface Use the highest-level interface already available: 1. If suitable `outlit_*` MCP or Pi tools are present, call them. 2. Otherwise, if the `outlit` CLI is installed, use it. 3. Otherwise, guide setup: - Coding agents: run `outlit onboard --agent --json`. Outside CI, it can start browser approval when no key is available, install this skill, validate access, and return next actions. - Skills only: run `outlit setup --yes` or `outlit setup skills`. - MCP clients: use the workspace URL from **Settings > CLI & MCP** and complete OAuth in the client. Do not hardcode a shared endpoint, bearer header, or API key into remote MCP configuration. ## Quick Chooser Tool availability depends on the MCP server or Pi tool policy. If a named tool is absent, use the CLI or ask the user to enable the appropriate toolset. | Need | Tool when exposed | CLI | |------|-------------------|-----| | Browse customers | `outlit_list_customers` | `outlit customers list` | | Browse customer-associated users | `outlit_list_users` | `outlit users list` | | Browse workspace users | `outlit_list_workspace_users` | `outlit ws-users list` | | Single account profile | `outlit_get_customer` | `outlit customers get` | | Current customer relationship | `outlit_get_customer_relationship` | `outlit customers relationship` | | Chronology | `outlit_get_timeline` | `outlit customers timeline` | | Known structured signals | `outlit_list_facts`, `outlit_get_fact` | `outlit facts list/get` | | Source enumeration and retrieval | `outlit_list_sources`, `outlit_get_source` | `outlit sources list/get` | | Thematic or fuzzy question | `outlit_search_customer_context` | `outlit search` | | Custom analytics | `outlit_schema`, then `outlit_query` | `outlit schema`, then `outlit sql` | | Customer ownership and access | `outlit_assign_customer_owner`, `outlit_grant_customer_access`, `outlit_update_customer_access`, `outlit_revoke_customer_access` | `outlit customers owner set/grant/revoke` | | Automation destinations | `outlit_list_destinations` and destination write tools | `outlit destinations list/get/create/update/enable/disable/archive` | | Integration readiness or setup | `outlit_get_integration_capabilities`, `outlit_begin_integration_setup`, `outlit_get_integration_setup_status`, `outlit_get_integration_status`, `outlit_setup_integration` | `outlit integrations setup/status` | | Activation setting | `outlit_get_customer_activation`, `outlit_preview_customer_activation`, `outlit_update_customer_activation` | `outlit activation get/preview/update/disable` | | Workspace timezone | `outlit_get_workspace_settings`, `outlit_update_workspace_settings` | `outlit settings get/update` | | Workspace Features | `outlit_list_features`, `outlit_create_feature`, `outlit_archive_feature` | `outlit features list/create/archive` | | Customer Feature usage | `outlit_get_customer_features` | `outlit customers features` | | Review current Attention items | `outlit_list_attention_items`, `outlit_get_attention_item` | `outlit attention list/get` | Customer-associated users belong to customer accounts. Workspace users are internal Outlit members used for ownership and access actions. Do not substitute one ID type for the other. Use customer lookups before SQL. SQL is for aggregates, cohorts, joins, time-series checks, and custom reporting. ## Working Rules - Start with the highest-level tool that can answer the question. - Gather evidence before drawing conclusions, and separate evidence from interpretation. - Cite the evidence kind: customer, user, workspace user, relationship item, timeline event, fact, search result, source, Attention item, Feature usage, or SQL result. - Say when data is sparse, stale, truncated, partial, or inconsistent and how that affects confidence. - Request only the fields or include sections needed. - Treat write operations as changes to the user's workspace. Assign owners, change access, configure integrations, or mutate destinations, activation, settings, and Features only when the user explicitly asks. - Do not treat integration `ready` status as proof that a sync or backfill finished or that customer data is current. ## Facts, Search, Sources, and Timeline - Use `facts list` to browse known structured intelligence for one account. - Public `factTypes` filters accept `CUSTOM`, `COMPANY_CHANGE`, `FUNDING_REVENUE`, `TECHNOLOGY`, `STRATEGY`, `COMPETITIVE`, `SENTIMENT`, `CHAMPION_RISK`, `EXPANSION`, `CHURN_RISK`, `TIMELINE`, `BUDGET`, `DECISION_MAKER`, `REQUIREMENTS`, `PRODUCT_USAGE`, `CONTACT_INFO`, `CONTACT_PREFERENCE`, `CONTACT_DEPARTURE`, `CONTACT_POSITION_CHANGE`, and `CONTACT_DISENGAGEMENT`. - Public `factCategories` filters accept `MEMORY`, `RELATIONSHIP`, and `CUSTOM`. - Contact-transition facts are neutral, source-backed observations about a known contact: - `CONTACT_DEPARTURE`: the contact left or is leaving the customer's company. Exclude temporary leave, ordinary out-of-office notices, candidates, and people discussed as part of the customer's own business. - `CONTACT_POSITION_CHANGE`: the contact changed title, department, team, or professional responsibility at the customer's company. This is not an Outlit relationship-role change; use `CONTACT_DEPARTURE` if the person left the company. - `CONTACT_DISENGAGEMENT`: the contact explicitly stopped participating, organizing, responding, or owning the initiative. A single unanswered message, scheduling friction, or an out-of-office notice is insufficient. It remains extractable but does not currently wake Churn; current contact-transition Churn signals cover only confirmed departures and position changes. - `CHAMPION_RISK` remains historical and readable, but new extraction uses the specific contact-transition types instead of inferring a broad relationship judgment. - Do not request internal anomaly-detector types such as `CORE_ACTION_DECAY`, `CADENCE_BREAK`, `QUIET_ACCOUNT`, `ACTIVATION_RATE_DROP`, or `FUNNEL_DROPOFF` as public fact filters. - Use `facts get` with a known fact ID for the canonical payload or best-effort `evidence`. - Use `search` for a specific question or theme, including cross-customer questions. Search returns grouped source and fact artifacts, not raw vector chunks. - Use `sources list` for deterministic enumeration of emails, calls, calendar events, support tickets, CRM opportunities, or Slack messages. - Use `sources get` when another result points to a concrete source and you need the exact artifact. - Use `timeline` when order, recency, or sequence matters. Supported generic source types are `EMAIL`, `CALL`, `CALENDAR_EVENT`, `SUPPORT_TICKET`, `OPPORTUNITY`, and `SLACK`. `CRM` and `CRM_OPPORTUNITY` are accepted aliases for opportunity filters. ## Authorization Outlit API keys are independent workspace principals. They do not inherit their creator's human permissions or customer access. Key presets are Read only, Personal CLI, Full workspace access, and Custom. Browser onboarding issues a Personal CLI key with read access plus creator-bound integration setup; it does not grant general workspace integration administration. Current read grants are: - `customer_intelligence:read` - `workspace_members:read` - `analytics:read` - `activation:read` - `workspace_settings:read` Current write or setup grants are: - `destinations:manage` - `behavior_metrics:manage` - `integrations:connect_own` - `integrations:manage` - `activation:manage` - `workspace_settings:manage` - `customer_access:manage` A valid key can still receive `403` when it lacks the required grant. Do not retry that failure. Ask a workspace admin to review the key under **Settings > API Keys**. Remote MCP OAuth uses the signed-in user's current workspace authorization instead of an Outlit API key. ## SQL Rules Call schema before writing SQL. - Use public analytics views, not backend table names: `activity`, `customers`, `users`, `revenue`. - Add explicit time filters to activity SQL. - Use `LIMIT`. - Divide money fields in cents by `100` for display. - Inspect JSON or trait column shapes before filtering nested values. - Keep SQL read-only. For ClickHouse syntax and query patterns, read [references/sql-reference.md](references/sql-reference.md). ## CLI Setup Install the CLI: ```bash curl -fsSL https://outlit.ai/install.sh | bash # Alternatives: npm install -g @outlit/cli brew install outlitai/tap/outlit ``` Credential resolution order is `--api-key`, `OUTLIT_API_KEY`, then stored credentials. ```bash outlit onboard --agent --json outlit auth login --browser --json outlit auth status outlit auth whoami outlit doctor --json ``` Plain `outlit auth login` automatically selects browser approval in a noninteractive agent shell outside CI. CI requires a key. `outlit setup --yes` and `outlit setup skills` install skills but do not configure MCP clients or integrations. If `onboard` is unavailable, run `outlit upgrade`, then use `outlit setup ` or `outlit setup skills`. ## CLI Output Behavior - Interactive terminal: readable tables, spinners, and colors. - Piped output, `--json`, CI, or `TERM=dumb`: JSON. - Successful JSON is written to stdout. JSON errors are written to stderr with a nonzero exit status. Agents should check the exit status and capture stderr instead of assuming every JSON payload is on stdout. ## MCP Setup Get the workspace URL from **Settings > CLI & MCP**: ```text https://mcp.outlit.ai/w//mcp ``` Add that URL directly to the MCP client and complete OAuth. Verify the connection with one of the tools actually exposed by the client. ## Pi and Tool Packages ```bash pi install npm:@outlit/pi export OUTLIT_API_KEY=ok_your_api_key pi ``` `@outlit/pi` registers `defaultToolNames` unless a custom policy is supplied. SQL and the broader public catalog are not enabled by default. Use `analyticalToolNames` for the default reads plus SQL, or `piToolNames` for the Pi-supported public catalog only when the agent should receive those capabilities. For custom TypeScript clients, `@outlit/tools` exports `publicToolContracts`, `publicToolNames`, `consumerToolPolicies`, `defaultToolNames`, `analyticalToolNames`, `piToolNames`, `cliToolNames`, `allPublicToolNames`, and `sqlToolNames`. ## Integrations Use `setup` to connect or repair a data source; use `status` to inspect readiness. The current CLI exposes two commands: ```text outlit integrations setup outlit integrations status [provider] ``` Interactive `setup` negotiates capabilities first. It can securely prompt for a credential, open a validated browser handoff, or ask the user to confirm a CRM or Mixpanel mapping. Do not ask the user to paste provider secrets into chat. Do not put secrets in model-visible tool calls, command arguments, logs, shell history, or process listings. When automation must supply provider configuration, have the user run the command in a trusted local terminal and send one strict JSON object through stdin: ```bash printf '%s\n' '{"credentials":{"apiKey":""}}' \ | outlit integrations setup fireflies --config-stdin --json ``` Use `--accept-recommended` only to accept the exact CRM recommendation returned by the current setup response. Explicit mappings also go through `--config-stdin`. JSON mode never prompts, opens a browser, or polls. It returns the setup result, including any handoff or required next step. `status` reports configuration readiness as `not_connected`, `awaiting_auth`, `setup_required`, `ready`, or `requires_intervention`. It does not expose setup-session or synchronization metadata. Disconnect integrations through the Outlit web app. The CLI does not expose destructive integration removal. ## Troubleshooting - Missing API key: use `outlit onboard --agent --json`, `outlit auth login`, or set `OUTLIT_API_KEY`. CI requires a key. - Valid key but `403`: inspect the key's grants under **Settings > API Keys**. - Setup issues: run `outlit doctor --json` and `outlit integrations status [provider] --json`. - Stale CLI or missing current commands: run `outlit upgrade`. - MCP auth issues: use the workspace URL and OAuth flow. Do not assume remote MCP requires an API key. - Empty data: inspect integration readiness and data freshness before concluding that a customer has no activity. ## Docs - Docs home: https://docs.outlit.ai/ - CLI overview: https://docs.outlit.ai/cli/overview - CLI commands: https://docs.outlit.ai/cli/commands - CLI integrations: https://docs.outlit.ai/cli/integrations - AI agent setup: https://docs.outlit.ai/cli/ai-agents - Agent skills: https://docs.outlit.ai/ai-integrations/skills - MCP integration: https://docs.outlit.ai/ai-integrations/mcp - Pi agents: https://docs.outlit.ai/ai-integrations/pi - Public tools API: https://docs.outlit.ai/api-reference/tools - API key validation: https://docs.outlit.ai/api-reference/validation - Customer context graph: https://docs.outlit.ai/concepts/customer-context-graph ## Common Prompts - "What changed for this customer this week?" - "Who is paying but inactive for 30 days?" - "Why does this account need attention?" - "What pricing objections show up in conversations?" - "Which Features are customers using before renewal?"