### Setup Development Environment with Bun

Source: https://github.com/outlitai/outlit-sdk/blob/main/README.md

Sets up the Outlit SDK development environment using Bun. This includes installing dependencies, building all packages, running tests, linting, type checking, and formatting the code. These commands are essential for contributing to the SDK.

```bash
# Install dependencies
bun install

# Build all packages
bun run build

# Run tests
bun run test

# Lint code
bun run lint

# Type check
bun run typecheck

# Format code
bun run format
```

--------------------------------

### Install Outlit CLI using npm or Homebrew

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/quickstart.mdx

Installs the Outlit Command Line Interface (CLI) globally using either npm or Homebrew. This is the first step to interacting with Outlit from your terminal.

```bash
npm install -g @outlit/cli
```

```bash
brew install outlitai/tap/outlit
```

--------------------------------

### Recommended Outlit Setup Command

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/ai-integrations/skills.mdx

Executes the recommended 'outlit setup' command with the '--yes' flag to automatically configure MCP and install necessary skills in a single operation.

```bash
outlit setup --yes
```

--------------------------------

### JSON Output for Auto-Setup

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Displays the result of the automatic AI agent setup process in JSON format, indicating detected, configured, and failed agents, as well as the status of agent skill installation.

```json
{
  "detected": ["cursor", "claude-code", "claude-desktop"],
  "configured": ["cursor", "claude-code", "claude-desktop"],
  "failed": [],
  "skills": { "success": true, "runner": "npx" }
}
```

--------------------------------

### Quick Start: Track Event with Rust SDK

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/rust.mdx

A basic example demonstrating how to initialize the Outlit client with your public key and track a 'feature_used' event associated with a user's email. It also shows how to properly shut down the client to ensure all events are flushed before the application exits. Requires a tokio runtime.

```rust
use outlit::{Outlit, email, fingerprint};

#[tokio::main]
async fn main() -> Result<(), outlit::Error> {
    let client = Outlit::builder("pk_your_public_key")
        .build()?;

    // Track with email (resolves immediately)
    client.track("feature_used", email("user@example.com"))
        .property("feature", "export")
        .send()
        .await?;

    // Flush before exit
    client.shutdown().await?;
    Ok(())
}
```

--------------------------------

### Installation

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Install the Node.js SDK using your preferred package manager.

```APIDOC
## Installation

Install the Node.js SDK using your preferred package manager:

<CodeGroup>
```bash npm
npm install --save @outlit/node
```

```bash pnpm
pnpm add @outlit/node
```

```bash yarn
yarn add @outlit/node
```

```bash bun
bun add @outlit/node
```
</CodeGroup>
```

--------------------------------

### Rust SDK Example Usage

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/plans/2025-01-27-implementation-plan.md

Provides a complete example of how to use the Outlit SDK in Rust. It demonstrates initializing the client with a provided API key and flush interval, tracking a 'signup' event with user email and properties, and properly shutting down the client. This example requires the 'tokio' runtime.

```rust
//! Outlit analytics SDK for Rust.
//!
//! # Example
//!
//! ```rust,no_run
//! use outlit::{Outlit, email};
//! use std::time::Duration;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), outlit::Error> {
//!     let client = Outlit::builder("pk_xxx")
//!         .flush_interval(Duration::from_secs(5))
//!         .build()?;
//!
//!     client.track("signup", email("user@example.com"))
//!         .property("plan", "pro")
//!         .send()
//!         .await?;
//!
//!     client.shutdown().await?;
//!     Ok(())
//! }
//! ```

mod builders;
mod client;
mod config;
mod error;
mod queue;
mod transport;
mod types;

pub use client::{
    CustomerMethods,
    Outlit,
    SendableBilling,
    SendableIdentify,
    SendableStage,
    SendableTrack,
    UserMethods,
};
pub use config::{Config, OutlitBuilder};
pub use error::Error;
pub use types::{
    BillingStatus,
    IngestPayload,
    IngestResponse,
    JourneyStage,
    SourceType,
    TrackerEvent,
};

// Identity helpers

/// Create an email identity.
pub fn email(e: impl Into<String>) -> Email {
    Email(e.into())
}

/// Create a user ID identity.
pub fn user_id(id: impl Into<String>) -> UserId {
    UserId(id.into())
}

/// Email identity wrapper.
#[derive(Debug, Clone)]
pub struct Email(pub(crate) String);

impl Email {
    /// Get the email as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<Email> for String {
    fn from(e: Email) -> String {
        e.0
    }
}

impl From<Email> for builders::Identity {
    fn from(e: Email) -> builders::Identity {
        builders::Identity::Email(e)
    }
}

/// User ID identity wrapper.
#[derive(Debug, Clone)]
pub struct UserId(pub(crate) String);

impl UserId {
    /// Get the user ID as a string slice.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl From<UserId> for String {
    fn from(id: UserId) -> String {
        id.0
    }
}

impl From<UserId> for builders::Identity {
    fn from(id: UserId) -> builders::Identity {
        builders::Identity::UserId(id)
    }
}

// Update OutlitBuilder to create client
impl OutlitBuilder {
    /// Build the Outlit client.
    pub fn build(self) -> Result<Outlit, Error> {
        let config = self.build_config()?;
        Outlit::from_config(config)
    }
}
```

--------------------------------

### Install Outlit CLI

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/overview.mdx

Instructions for installing the Outlit CLI using different package managers or by downloading a binary. It also includes a command to verify the installation.

```bash
npm install -g @outlit/cli
```

```bash
brew install outlitai/tap/outlit
```

```bash
outlit --version
```

--------------------------------

### Install Outlit SDK Packages

Source: https://github.com/outlitai/outlit-sdk/blob/main/README.md

Installs the appropriate Outlit SDK package based on the target environment. Use `@outlit/browser` for web applications, `@outlit/node` for server-side applications, and `@outlit/core` for custom implementations.

```bash
# For browser applications
npm install @outlit/browser

# For Node.js applications
npm install @outlit/node

# For custom implementations
npm install @outlit/core
```

--------------------------------

### Outlit Doctor Example Output

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Sample output from the `outlit doctor` command, showing the status of various checks including CLI version, API key validation, and individual agent configurations. It highlights successful checks and potential issues.

```text
  Outlit Doctor

  ✓ CLI version: v0.1.0 (latest)
  ✓ API key: Found (ok_ab...1234) via config
  ✓ API validation: Key is valid
  ✓ Cursor: Installed, Outlit MCP configured
  ! Claude Code: Installed, but Outlit MCP not verified
  ✓ Claude Desktop: Installed, Outlit MCP configured

  Everything works, 1 suggestion(s).
```

--------------------------------

### Full Outlit SDK Integration Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/script.mdx

A complete HTML example demonstrating the integration of the Outlit SDK, including user identification via form submission and event tracking on button clicks. It incorporates the SDK initialization script.

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome</h1>
  
  <form id="contact-form">
    <input name="email" type="email" placeholder="Email" />
    <input name="name" type="text" placeholder="Name" />
    <button type="submit">Contact Us</button>
  </form>

  <button id="cta" onclick="handleCTA()">Get Started</button>

  <script>
    function handleCTA() {
      window.outlit.track('cta_clicked', {
        location: 'hero',
        page: window.location.pathname
      });
    }

    // Identify after form submission
    document.getElementById('contact-form').addEventListener('submit', function(e) {
      const email = e.target.querySelector('[name="email"]').value;
      const name = e.target.querySelector('[name="name"]').value;
      
      window.outlit.identify({
        email: email,
        traits: { name: name }
      });
    });
  </script>

  <script>
    !function(w,d,src,key,auto){
      if(w.outlit&&w.outlit._loaded)return;
      var o=w.outlit=w.outlit||{_q:[]};
      function stub(target,prefix,methods){
        for(var i=0;i<methods.length;i++){
          var m=methods[i];
          target[m]=target[m]||function(mm){
            return function(){o._q.push([prefix?prefix+"."+mm:mm,[].slice.call(arguments)])};
          }(m);
        }
      }
      stub(o,"",["init","track","identify","enableTracking","disableTracking","isTrackingEnabled","getVisitorId","setUser","clearUser"]);
      o.user=o.user||{};o.customer=o.customer||{};
      stub(o.user,"user",["identify","activate","engaged","inactive"]);
      stub(o.customer,"customer",["trialing","paid","churned"]);
      var s=d.createElement("script");s.async=1;s.src=src;
      s.dataset.publicKey=key;if(auto!==undefined)s.dataset.autoTrack=auto;
      (d.body||d.head).appendChild(s);
    }(window,document,"https://cdn.outlit.ai/stable/outlit.js","pk_your_public_key");
  </script>
</body>
</html>
```

--------------------------------

### Clone and Install Outlit SDK Dependencies

Source: https://github.com/outlitai/outlit-sdk/blob/main/CONTRIBUTING.md

Instructions for cloning the Outlit SDK repository and installing its dependencies using npm. This is a prerequisite for local development.

```bash
git clone https://github.com/your-username/outlit-sdk.git
cd outlit-sdk
npm install
```

--------------------------------

### Authenticate with Outlit CLI

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/quickstart.mdx

Logs into your Outlit account using the CLI. If you don't have an account, you can sign up directly from the terminal. The CLI stores API keys securely.

```bash
outlit auth login
```

```bash
outlit auth signup
```

--------------------------------

### Express.js Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Example of integrating Outlit SDK with an Express.js application.

```APIDOC
## POST /api/reports/export (Express.js Integration)

### Description
This example demonstrates how to use the Outlit SDK within an Express.js middleware and route handler to track a 'report_exported' event.

### Method
POST

### Endpoint
/api/reports/export

### Parameters
#### Request Body
- **user** (object) - Required - User details.
  - **email** (string) - Required - User's email.
- **format** (string) - Required - The format of the report to be exported.

### Request Example
```json
{
  "user": {
    "email": "user@example.com"
  },
  "format": "pdf"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

### Notes
- Assumes `req.outlit` is populated by middleware.
- Includes graceful shutdown on SIGTERM.
```

--------------------------------

### Serverless Functions Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Example for using Outlit SDK in serverless functions like AWS Lambda or Vercel.

```APIDOC
## POST / (Serverless Functions Integration)

### Description
Demonstrates tracking an event within a generic serverless function (e.g., AWS Lambda, Vercel) and highlights the critical need to call `flush()` before returning.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **email** (string) - Required - The email of the user.
- **action** (string) - Required - The name of the event action to track.

### Request Example
```json
{
  "email": "user@example.com",
  "action": "user_action_performed"
}
```

### Response
#### Success Response (200)
- **statusCode** (integer) - HTTP status code.
- **body** (string) - Response body message.

#### Response Example
```json
{
  "statusCode": 200,
  "body": "OK"
}
```

### Notes
- **Crucial**: Always call `await outlit.flush()` before returning in serverless environments to ensure events are sent.
```

--------------------------------

### Install Node.js SDK using npm, pnpm, yarn, or bun

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Installs the Outlit Node.js SDK package. Choose the command corresponding to your preferred package manager (npm, pnpm, yarn, or bun).

```bash
npm install --save @outlit/node
```

```bash
pnpm add @outlit/node
```

```bash
yarn add @outlit/node
```

```bash
bun add @outlit/node
```

--------------------------------

### Outlit CLI Whoami Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/overview.mdx

An example output of the `outlit auth whoami` command, which validates the API key and prints a single line with the masked key and its source, suitable for scripting.

```bash
$ outlit auth whoami
ok_ab...1234 (config)
```

--------------------------------

### Next.js API Routes Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Example of using Outlit SDK in Next.js API routes for tracking subscription upgrades.

```APIDOC
## POST /api/subscription/upgrade (Next.js API Routes Integration)

### Description
This example shows how to track a 'subscription_upgraded' event and update customer billing status within a Next.js API route.

### Method
POST

### Endpoint
/api/subscription/upgrade

### Parameters
#### Request Body
- **userId** (string) - Required - The ID of the user.
- **email** (string) - Required - The email of the user.
- **newPlan** (string) - Required - The name of the new subscription plan.
- **amount** (number) - Required - The amount associated with the new plan.
- **domain** (string) - Required - The domain of the customer account.

### Request Example
```json
{
  "userId": "user123",
  "email": "user@example.com",
  "newPlan": "premium",
  "amount": 199,
  "domain": "acme.com"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```

### Notes
- Emphasizes the importance of calling `outlit.flush()` in serverless environments.
```

--------------------------------

### Outlit CLI Authentication Status Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/overview.mdx

An example output of the `outlit auth status` command, indicating a successful authentication and showing the masked API key and its source.

```bash
$ outlit auth status
✓ Authenticated
  Key:    ok_ab...1234
  Source: config
```

--------------------------------

### Check Exit Code with Bash

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Demonstrates how to use the 'outlit doctor' command and pipe its exit code to another command. This is useful for CI pipelines to detect setup issues.

```bash
outlit doctor || echo "Setup issues detected"
```

--------------------------------

### Setup OpenClaw AI Agent with Outlit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Configures the OpenClaw AI agent by writing an Outlit intelligence skill to the OpenClaw skills directory. OpenClaw automatically loads skills from `~/clawd/skills/` or `~/.openclaw/skills/`.

```bash
outlit setup openclaw
```

--------------------------------

### Setup VS Code AI Agent with Outlit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Configures VS Code to connect to Outlit via MCP. This command writes the configuration to `.vscode/mcp.json` in the current directory. Note that VS Code uses a `servers` key instead of `mcpServers`.

```bash
outlit setup vscode
```

--------------------------------

### JSON Credentials File Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/configuration.mdx

The `credentials.json` file stores the API key for authentication. It is stored in the config directory with restrictive file permissions (0600).

```json
{
  "apiKey": "ok_your_api_key_here"
}
```

--------------------------------

### Generate Shell Completions

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Provides commands to generate shell completion scripts for Bash, Zsh, and Fish. These scripts enhance user experience by providing command-line autocompletion.

```bash
outlit completions bash >> ~/.bash_completion
source ~/.bash_completion
```

```zsh
outlit completions zsh >> ~/.zshrc
exec zsh
```

```fish
outlit completions fish > ~/.config/fish/completions/outlit.fish
```

--------------------------------

### Verify Outlit Agent Skills Installation

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/ai-integrations/skills.mdx

Verifies that the Outlit agent skills have been successfully installed on the system. This command checks for the presence and correct setup of the installed skills.

```bash
outlit doctor
```

--------------------------------

### Query Customer Data with Outlit CLI

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/quickstart.mdx

Demonstrates how to query customer data using the Outlit CLI. This includes listing customers, viewing a customer's timeline, performing natural language searches, and running raw SQL queries.

```bash
# List your customers
outlit customers list

# See a customer's full timeline
outlit customers timeline acme.com

# Search with natural language
outlit search "who signed up this week"

# Run SQL directly
outlit sql "SELECT domain, billing_status, mrr_cents FROM customers ORDER BY mrr_cents DESC LIMIT 10"
```

--------------------------------

### Initialize Outlit SDK (JavaScript)

Source: https://github.com/outlitai/outlit-sdk/blob/main/packages/browser/__tests__/e2e/fixtures/form-no-email.html

Initializes the Outlit SDK asynchronously. It includes methods for tracking, identifying users, and managing user/customer states. The SDK is loaded from a script tag and configured with a public key and optional auto-tracking.

```javascript
!function(w,d,src,key,auto){ if(w.outlit&&w.outlit._loaded)return; var o=w.outlit=w.outlit||{_q:[]}; function stub(target,prefix,methods){ for(var i=0;i<methods.length;i++){ var m=methods[i]; target[m]=target[m]||function(mm){ return function(){o._q.push([prefix?prefix+"."+mm:mm,[].slice.call(arguments)])}; }(m); } } stub(o,"",["init","track","identify","enableTracking","isTrackingEnabled","getVisitorId","setUser","clearUser"])
; o.user=o.user||{};o.customer=o.customer||{}; stub(o.user,"user",["identify","activate","engaged","inactive"])
; stub(o.customer,"customer",["trialing","paid","churned"])
; var s=d.createElement("script");s.async=1;s.src=src;
 s.dataset.publicKey=key;if(auto!==undefined)s.dataset.autoTrack=auto;
 (d.body||d.head).appendChild(s);
}(window,document,"/outlit.global.js","pk_test_key_12345");
```

--------------------------------

### Querying Customers via Outlit CLI

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/how-it-works.mdx

Demonstrates how to use the Outlit CLI to list paying customers, retrieve detailed customer profiles including their timeline, and perform natural language searches. It also shows how to execute SQL queries against the Outlit graph.

```bash
# List paying customers sorted by revenue
outlit customers list --billing-status PAYING --sort mrr

# Get a customer profile with timeline
outlit customers get acme.com --include users,revenue,timeline

# Natural language search
outlit search "customers who signed up from Google Ads last month"

# SQL
outlit sql "SELECT domain, mrr_cents FROM customers WHERE billing_status = 'PAYING'"
```

--------------------------------

### Setup Gemini CLI AI Agent with Outlit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Configures the Gemini CLI to connect to Outlit via MCP. This command uses the Gemini CLI to register the MCP server. Requires the `gemini` CLI tool to be installed.

```bash
outlit setup gemini
```

--------------------------------

### Browser SDK Installation and Initialization

Source: https://context7.com/outlitai/outlit-sdk/llms.txt

Load the Outlit SDK via a script tag for non-bundled web applications. This method allows for quick integration without a build process. Initialization requires a public key, and subsequent calls track events, identify users, and manage user journey stages.

```html
<!-- Option 1: From CDN (latest stable) -->
<script src="https://cdn.outlit.ai/stable/outlit.js"></script>

<!-- Option 2: Specific version -->
<script src="https://cdn.outlit.ai/v1.4.1/outlit.js"></script>

<!-- Option 3: Canary (latest from main branch) -->
<script src="https://cdn.outlit.ai/canary/outlit.js"></script>

<script>
  // Initialize
  window.outlit.init({ publicKey: 'pk_your_public_key' })

  // Track events
  window.outlit.track('page_loaded', { page: window.location.pathname })

  // Identify users
  window.outlit.identify({
    email: 'user@example.com',
    traits: { name: 'Jane Doe' }
  })

  // User journey stages
  window.outlit.user().activate({ milestone: 'signup' })

  // Customer billing
  window.outlit.customer().paid({
    domain: 'customer.com',
    properties: { plan: 'pro' }
  })
</script>
```

--------------------------------

### Setup Claude Code AI Agent with Outlit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Configures the Claude Code AI agent to connect to Outlit via MCP. This command uses the Claude CLI to register the MCP server. Requires the `claude` CLI tool to be installed.

```bash
outlit setup claude-code
```

--------------------------------

### Cursor AI Agent MCP Configuration

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Example JSON configuration for the Cursor AI agent, specifying the Outlit MCP server URL and authorization headers.

```json
{
  "mcpServers": {
    "outlit": {
      "url": "https://mcp.outlit.ai/mcp",
      "headers": {
        "Authorization": "Bearer ok_your_api_key"
      }
    }
  }
}
```

--------------------------------

### Outlit Doctor JSON Diagnostic Results

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Example JSON output from the `outlit doctor --json` command, detailing the status and messages for each performed check, including CLI version, API key, API validation, and agent configurations.

```json
{
  "ok": true,
  "checks": [
    { "name": "CLI version", "status": "pass", "message": "v0.1.0 (latest)" },
    { "name": "API key", "status": "pass", "message": "Found (ok_ab...1234) via config" },
    { "name": "API validation", "status": "pass", "message": "Key is valid" },
    { "name": "Cursor", "status": "pass", "message": "Installed, Outlit MCP configured" }
  ]
}
```

--------------------------------

### Claude Desktop AI Agent MCP Configuration

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Example JSON configuration for the Claude Desktop AI agent, using a command-based approach to connect to Outlit via MCP. It specifies the command to run and environment variables, including the Outlit API key.

```json
{
  "mcpServers": {
    "outlit": {
      "command": "outlit",
      "args": ["mcp", "serve"],
      "env": {
        "OUTLIT_API_KEY": "ok_your_api_key"
      }
    }
  }
}
```

--------------------------------

### Configure Outlit SDK Environment Variables

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/sveltekit.mdx

Shows how to set up environment variables for the Outlit SDK, including the public key for client-side use and the private key for server-side API routes. This is typically done in a `.env` file.

```bash
# .env

# Public key (used in browser)
PUBLIC_OUTLIT_KEY=pk_your_public_key_here

# Private key (used in server API routes)
OUTLIT_PRIVATE_KEY=sk_your_private_key_here

```

--------------------------------

### Wait for Outlit SDK Initialization and Get Visitor ID

Source: https://github.com/outlitai/outlit-sdk/blob/main/packages/browser/__tests__/e2e/fixtures/test-page.html

This JavaScript function, `waitForOutlit`, recursively checks for the Outlit SDK's initialization status (`window.outlit._initialized`). Once initialized, it executes a callback function, which in this example, updates a status element with the visitor ID obtained from `window.outlit.getVisitorId()`. It uses a short timeout to poll for readiness.

```javascript
// Wait for SDK to be ready function waitForOutlit(callback) { if (window.outlit && window.outlit._initialized) { callback(); } else { setTimeout(() => waitForOutlit(callback), 50); } } waitForOutlit(() => { document.getElementById('status-text').textContent = 'SDK Initialized. Visitor ID: ' + (window.outlit.getVisitorId() || 'none'); });
```

--------------------------------

### Manually Install Outlit Agent Skills

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/ai-integrations/skills.mdx

Manually installs specific Outlit agent skills, such as 'outlit-cli' and 'outlit-sdk', from a GitHub repository using npx. The '-y' flag confirms installation, and '-g' installs globally.

```bash
npx -y skills add https://github.com/OutlitAI/outlit-agent-skills --skill outlit-cli --skill outlit-sdk -y -g
```

--------------------------------

### Quick Start: Initialize and track an event with Node.js SDK

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/nodejs.mdx

Initializes the Outlit Node.js SDK with a public key and demonstrates tracking a 'subscription_upgraded' event for a user. It's crucial to call `outlit.flush()` before the process exits to ensure all queued events are sent.

```typescript
import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: 'pk_your_public_key'
})

// Track an event
outlit.track({
  email: 'user@example.com',
  eventName: 'subscription_upgraded',
  properties: {
    fromPlan: 'starter',
    toPlan: 'pro',
    mrr: 99
  }
})

// Important: flush before process exits
await outlit.flush()
```

--------------------------------

### Quick Start: Track Events and Identify Users with Outlit SDK in Rust

Source: https://github.com/outlitai/outlit-sdk/blob/main/crates/outlit/README.md

Initialize the Outlit client with your public key and demonstrate tracking custom events, identifying users with traits, and managing user journey stages. Ensure to flush events before shutting down the client.

```rust
use outlit::{Outlit, email};
use std::time::Duration;

#[tokio::main] async fn main() -> Result<(), outlit::Error> {
    // Initialize the client
    let client = Outlit::builder("pk_your_public_key")
        .flush_interval(Duration::from_secs(10))
        .build()?;

    // Track a custom event
    client.track("signup", email("user@example.com"))
        .property("plan", "pro")
        .property("source", "landing_page")
        .send()
        .await?;

    // Identify a user (update traits)
    client.identify(email("user@example.com"))
        .user_id("usr_123")
        .trait_("name", "John Doe")
        .trait_("company", "Acme Inc")
        .send()
        .await?;

    // User journey stages
    client.user().activate(email("user@example.com"))
        .property("onboarding_completed", true)
        .send()
        .await?;

    // Customer billing
    client.customer().paid("acme.com")
        .customer_id("cust_123")
        .stripe_customer_id("cus_xxx")
        .send()
        .await?;

    // Important: Flush before shutdown!
    client.shutdown().await?;

    Ok(())
}
```

--------------------------------

### Initialize and Track Events using Singleton API (Browser)

Source: https://github.com/outlitai/outlit-sdk/blob/main/README.md

Demonstrates the singleton API for initializing and using the Outlit browser SDK. The `init` function is called once at application startup, and subsequent calls to `track`, `user`, and `customer` can be made directly from the imported functions.

```typescript
import { init, track, user, customer } from '@outlit/browser'

// Initialize once at app startup
init({ publicKey: 'pk_xxx' })

// Then use anywhere
track('page_viewed', { page: '/home' })
user().identify({ email: 'user@example.com' })
customer().paid({ domain: 'acme.com', properties: { plan: 'pro' } })
```

--------------------------------

### Setup Cursor AI Agent with Outlit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/ai-agents.mdx

Configures the Cursor AI agent to connect to Outlit via MCP. This command writes the Outlit MCP server configuration to `~/.cursor/mcp.json`. Cursor needs to be restarted after setup.

```bash
outlit setup cursor
```

--------------------------------

### Configure Outlit Environment Variables

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/nuxt.mdx

This example shows how to configure public and private keys for the Outlit SDK using a .env file. The public key is for client-side use, while the private key is strictly for server-side API routes.

```bash
# .env

# Public key (used in browser)
NUXT_PUBLIC_OUTLIT_KEY=pk_your_public_key_here

# Private key (used in server API routes)
OUTLIT_PRIVATE_KEY=sk_your_private_key_here
```

--------------------------------

### TypeScript Configuration for Outlit SDK

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/sveltekit.mdx

Provides a TypeScript example for initializing the Outlit SDK with specific options, including the public key, page view tracking, and flush interval. It demonstrates the use of the `OutlitOptions` type for type safety.

```typescript
import outlit, { type OutlitOptions } from '@outlit/browser'

const options: OutlitOptions = {
  publicKey: PUBLIC_OUTLIT_KEY,
  trackPageviews: true,
  flushInterval: 5000
}

outlit.init(options)

```

--------------------------------

### Facts JSON Response Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/commands.mdx

Example JSON structure for the response of the `outlit facts` command, detailing fact information and pagination.

```json
{
  "items": [
    {
      "id": "fact-uuid",
      "customerId": "customer-uuid",
      "type": "SIGNAL",
      "title": "Budget concerns raised",
      "severity": "HIGH",
      "generatedAt": "2025-02-10T15:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "total": 12
  }
}
```

--------------------------------

### Querying Customer Data with Outlit CLI

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/concepts/customer-context-graph.mdx

Demonstrates how to query customer data, including their timeline and associated facts, using the Outlit command-line interface (CLI). This allows for a comprehensive view of customer interactions and insights.

```bash
outlit customers get acme.com --include timeline,facts
```

--------------------------------

### Activating a User in Outlit SDK

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/concepts/customer-context-graph.mdx

Illustrates the manual instrumentation required to mark a user as 'activated' within the Outlit SDK. This is crucial for defining product-specific onboarding completion or key milestone achievement.

```javascript
user.activate()
```

--------------------------------

### Users List JSON Response Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/commands.mdx

Example JSON structure for the response of the `outlit users list` command, detailing user information and pagination.

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

--------------------------------

### Deploy Browser SDK to CDN (Bash)

Source: https://github.com/outlitai/outlit-sdk/blob/main/README.md

These bash commands are used to deploy the browser SDK's IIFE bundle to Google Cloud Storage. They handle deploying to canary, stable, and versioned release paths, utilizing specific npm scripts.

```bash
cd packages/browser && bun run deploy:canary   # Deploy to canary
```

```bash
cd packages/browser && bun run deploy:stable   # Deploy to stable (requires confirmation)
```

```bash
cd packages/browser && bun run deploy:version  # Deploy versioned release
```

--------------------------------

### Initialize and Track Events with Outlit SDK (Rust)

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/plans/2025-01-27-implementation-plan.md

Demonstrates how to initialize the Outlit client with a public key and configuration options, then track custom events with properties and send them. It also shows how to identify users and manage customer billing events. Includes flushing the client before shutdown.

```rust
use outlit::{Outlit, email};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), outlit::Error> {
    // Initialize the client
    let client = Outlit::builder("pk_your_public_key")
        .flush_interval(Duration::from_secs(10))
        .build()?;

    // Track a custom event
    client.track("signup", email("user@example.com"))
        .property("plan", "pro")
        .property("source", "landing_page")
        .send()
        .await?;

    // Identify a user (update traits)
    client.identify(email("user@example.com"))
        .user_id("usr_123")
        .trait_("name", "John Doe")
        .trait_("company", "Acme Inc")
        .send()
        .await?;

    // User journey stages
    client.user().activate(email("user@example.com"))
        .property("onboarding_completed", true)
        .send()
        .await?;

    // Customer billing
    client.customer().paid("acme.com")
        .customer_id("cust_123")
        .stripe_customer_id("cus_xxx")
        .send()
        .await?;

    // Important: Flush before shutdown!
    client.shutdown().await?;

    Ok(())
}
```

--------------------------------

### Customer Timeline JSON Response Example

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/cli/commands.mdx

Example JSON structure for the response of the `outlit customers timeline` command, detailing event information and pagination.

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

--------------------------------

### Example Outlit SDK Commit Message

Source: https://github.com/outlitai/outlit-sdk/blob/main/CONTRIBUTING.md

An example of a well-formatted commit message for the Outlit SDK, following best practices for clarity and conciseness, including referencing issues.

```text
Add automatic page view tracking to browser SDK

- Implement page view tracking on navigation
- Add configuration options for auto-tracking
- Update tests and documentation

Fixes #123
```

--------------------------------

### Mock Server Setup for Outlit SDK Integration Tests (Rust)

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/plans/2025-01-27-implementation-plan.md

This snippet demonstrates setting up a mock HTTP server using `wiremock` to simulate responses from the Outlit API. It's used for integration testing the SDK's behavior, such as event flushing and shutdown.

```rust
let mock_server = MockServer::start().await;

Mock::given(method("POST"))
    .respond_with(ResponseTemplate::new(200).set_body_json(json!({
        "success": true,
        "processed": 5
    })))
    .expect(1)
    .mount(&mock_server)
    .await;
```

--------------------------------

### Initialize and Track Events in Node.js

Source: https://github.com/outlitai/outlit-sdk/blob/main/README.md

Initializes the Outlit Node.js SDK and demonstrates tracking server-side events, identifying users, and managing customer billing status. It requires a public key and includes a `flush` method to ensure all queued events are sent before application shutdown.

```typescript
import { Outlit } from '@outlit/node'

const outlit = new Outlit({
  publicKey: 'pk_xxx',
})

// Track server-side events (requires identity)
outlit.track('api_request', {
  email: 'user@example.com',
  properties: {
    endpoint: '/api/users',
    method: 'GET',
    status: 200,
  },
})

// Identify a user
outlit.user.identify({
  email: 'user@example.com',
  traits: { plan: 'pro' },
})

// Mark customer billing status
outlit.customer.paid({
  customerId: 'cust_123',
  properties: { plan: 'pro' },
})

// Flush events before shutdown
await outlit.flush()
```

--------------------------------

### Install Rust SDK with Cargo

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/server/rust.mdx

This command adds the Outlit SDK as a dependency to your Rust project using Cargo, the Rust package manager. Ensure you have Cargo installed and configured.

```bash
cargo add outlit
```

--------------------------------

### Initialize Outlit SDK with Lucia in SvelteKit

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/sveltekit.mdx

Initializes the Outlit SDK in the browser environment within a SvelteKit layout. It sets up user tracking based on authentication status and page data. Requires the public Outlit key from environment variables.

```svelte
<script>
  import { browser } from '$app/environment'
  import { page } from '$app/stores'
  import outlit from '@outlit/browser'
  import { onMount } from 'svelte'

  onMount(() => {
    if (browser) {
      outlit.init({
        publicKey: PUBLIC_OUTLIT_KEY,
        trackPageviews: true,
      })
    }
  })

  $: if (browser && $page.data.user) {
    outlit.setUser({
      email: $page.data.user.email,
      userId: $page.data.user.id,
      traits: {
        name: $page.data.user.name
      }
    })
  } else if (browser && !$page.data.user) {
    outlit.clearUser()
  }
</script>

<slot />

```

--------------------------------

### Create Account with Outlit CLI

Source: https://context7.com/outlitai/outlit-sdk/llms.txt

Command to create a new account using the Outlit CLI. This is the initial step for new users to register and gain access to Outlit services.

```bash
outlit auth signup
```

--------------------------------

### Install Outlit Agent Skills

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/ai-integrations/mcp.mdx

Installs Outlit agent skills to enhance AI agent context about query patterns, SDK integration, and best practices. This command is typically run in a bash environment.

```bash
outlit setup skills
```

--------------------------------

### Outlit API: init()

Source: https://github.com/outlitai/outlit-sdk/blob/main/docs/tracking/browser/npm.mdx

The `outlit.init(options)` method initializes the tracker and must be called before any other Outlit methods. It requires a public key and accepts various configuration options.

```typescript
import outlit from '@outlit/browser'

outlit.init({ publicKey: 'pk_xxx' })
```