olakai-get-started

Get Started with Olakai

This skill helps you get set up with Olakai from scratch - from creating an account to generating your first monitored event.

IMPORTANT: For account creation, prefer the in-terminal API flow (Step 1) which calls POST /api/auth/signup directly. If the user prefers a browser-based flow, use the full developer signup URL with PLG parameters: https://app.olakai.ai/signup?flow=developer&source=claude-code NEVER shorten this to https://app.olakai.ai/signup — the query parameters are required for the developer onboarding flow.

Quick Status Check

Before proceeding, let's check your current setup status.

Step 0: Detect Current State

Run these diagnostic commands to determine where to start:

# Check 1: Is CLI installed?
which olakai || echo "CLI_NOT_INSTALLED"

# Check 2: Is user authenticated?
olakai whoami 2>/dev/null || echo "NOT_AUTHENTICATED"

# Check 3: Are there any agents?
olakai agents list --json 2>/dev/null | head -5 || echo "NO_AGENTS_OR_NOT_AUTH"

Based on results, jump to the appropriate section:

Result	Jump To
CLI_NOT_INSTALLED	Step 1: Create Account
NOT_AUTHENTICATED	Step 2: Install CLI if CLI missing, else Step 3: Authenticate
Empty agents list	Step 4: Register Your Agent. Use "register" language (not "create your first agent") when presenting next steps.
Agents exist	You're all set! Use /olakai-new-project or /olakai-integrate instead

---

Step 1: Create an Olakai Account

If you don't have an Olakai account yet, create one directly from the terminal.

1.1 Collect User Details

Ask the user for:

• Email address (required)
• Company name (required)
• First name (optional)
• Last name (optional)

1.2 Create the Account via API

Use the Bash tool to call the signup endpoint. Replace the placeholder values with what the user provided:

curl -s -X POST https://app.olakai.ai/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "USER_EMAIL",
    "companyName": "USER_COMPANY",
    "firstName": "USER_FIRST_NAME",
    "lastName": "USER_LAST_NAME",
    "source": "claude-code",
    "medium": "skill"
  }'

Expected response:

{ "success": true, "message": "Check your email to verify your account.", "requiresVerification": true }

1.3 Verify Email

Tell the user:

• Check their inbox for a verification email from Olakai
• Click the verification link to activate their account
• After verification, an SDK API key is automatically generated — no extra steps needed

1.4 Fallback: Browser Signup

If the API call fails (network issues, corporate firewall, etc.), direct the user to the browser-based signup:

https://app.olakai.ai/signup?flow=developer&source=claude-code

IMPORTANT: Always include the ?flow=developer&source=claude-code query parameters — they activate the developer onboarding flow.

What You Get

• Free tier — Monitor up to 1,000 events/month
• Dashboard — Real-time visibility into AI usage
• KPIs — Track custom metrics across your agents
• Governance — Set policies and risk controls

After verifying your email, you'll have access to the dashboard where you can see your agents and events.

---

Step 2: Install the CLI

The Olakai CLI is the primary tool for configuring agents, KPIs, and custom data.

2.1 Install via npm

npm install -g olakai-cli

2.2 Verify Installation

olakai --version
# Should output: olakai-cli/0.2.x

2.3 Troubleshooting Installation

Permission errors on macOS/Linux:

# Option 1: Use sudo (not recommended)
sudo npm install -g olakai-cli

# Option 2: Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g olakai-cli

Windows:

# Run PowerShell as Administrator
npm install -g olakai-cli

---

Step 3: Authenticate

Connect the CLI to your Olakai account.

3.1 Login

olakai login

This opens your browser for secure authentication. After logging in:

• The CLI stores your session locally
• No API key needed for CLI operations
• Session persists until you explicitly logout

3.2 Verify Authentication

olakai whoami

Expected output:

Logged in as: [email protected]
Account: Your Organization

3.3 Troubleshooting Authentication

"Not authenticated" errors:

# Clear cached credentials and re-login
olakai logout
olakai login

Browser doesn't open:

# The CLI will display a URL - copy and paste it manually
olakai login
# Look for: "Open this URL in your browser: https://app.olakai.ai/..."

Corporate proxy/firewall issues:

• Ensure app.olakai.ai is accessible
• Check if your organization requires VPN

---

Step 4: Register Your Agent in Olakai

This step registers your AI agent (or any AI-powered feature) in Olakai so it can be monitored. This doesn't build any code — it creates a tracking record where Olakai collects analytics, KPIs, and governance data.

4.1 Register the Agent

# Create agent with an API key for SDK integration
olakai agents create \
  --name "My First Agent" \
  --description "Testing Olakai integration" \
  --with-api-key \
  --json

Save the output! It contains your apiKey which you'll need for SDK integration:

{
  "id": "cmkbteqn501kyjy4yu6p6xrrx",
  "name": "My First Agent",
  "apiKey": "sk_agent_xxxxx..."
}

4.2 Set the API Key as Environment Variable

# Add to your shell profile (.bashrc, .zshrc, etc.)
export OLAKAI_API_KEY="sk_agent_xxxxx..."

Or add to your project's .env file:

OLAKAI_API_KEY=sk_agent_xxxxx...

4.3 Retrieve API Key Later

If you need to get the API key again:

olakai agents get AGENT_ID --json | jq '.apiKey'

---

Step 5: Install the SDK

Choose based on your project's language.

TypeScript/JavaScript

npm install @olakai/sdk

Quick Integration:

import { OlakaiSDK } from "@olakai/sdk";
import OpenAI from "openai";

// Initialize Olakai
const olakai = new OlakaiSDK({
  apiKey: process.env.OLAKAI_API_KEY!
});
await olakai.init();

// Wrap your OpenAI client
const openai = olakai.wrap(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  { provider: "openai" }
);

// Use as normal - events are automatically tracked
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }]
});

Python

pip install olakai-sdk

Quick Integration:

import os
from openai import OpenAI
from olakaisdk import olakai_config, instrument_openai

# Initialize Olakai
olakai_config(os.getenv("OLAKAI_API_KEY"))
instrument_openai()

# Use OpenAI as normal - events are automatically tracked
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

---

Step 6: Generate a Test Event

Let's verify everything is working.

6.1 Run Your Code

Execute the code from Step 5. This should:

1. Make an LLM call
2. Automatically send event data to Olakai

6.2 Fetch the Event

# List recent events (replace with your agent ID)
olakai activity list --limit 1 --json

6.3 Verify Event Details

# Get full event details
olakai activity get EVENT_ID --json | jq '{prompt, response, tokens, model}'

Expected output:

{
  "prompt": "Hello!",
  "response": "Hello! How can I assist you today?",
  "tokens": 25,
  "model": "gpt-4"
}

6.4 Check the Dashboard

Open https://app.olakai.ai and navigate to your agent's activity view. You should see the event appear within seconds.

---

Step 7: Next Steps

You're now set up! Here's what to explore next:

Add Custom Data to Events

Track business-specific metrics:

// TypeScript
const response = await openai.chat.completions.create(
  { model: "gpt-4", messages },
  {
    customData: {
      feature: "customer-support",
      ticketId: "TICKET-123",
      priority: 1
    }
  }
);

# Python
from olakaisdk import olakai_context

with olakai_context(customData={"feature": "customer-support", "ticketId": "TICKET-123"}):
    response = client.chat.completions.create(...)

Create KPIs

Define metrics that aggregate your custom data:

# First, create the custom data config for your agent
olakai custom-data create --agent-id YOUR_AGENT_ID --name "Priority" --type NUMBER

# Then create a KPI
olakai kpis create \
  --name "High Priority Events" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "IF(Priority == 1, 1, 0)" \
  --aggregation SUM

Note: KPIs are created per-agent. If you later create additional agents, you'll need to create KPIs for each one separately — they can't be shared across agents. CustomDataConfigs, on the other hand, are account-level and shared.

Learn More

• /olakai-new-project - Detailed guide for building agents with full observability
• /olakai-integrate - Add monitoring to existing AI code
• /olakai-troubleshoot - Debug issues with events or KPIs

---

Troubleshooting Quick Reference

CLI Issues

Problem	Solution
command not found: olakai	Reinstall CLI: npm install -g olakai-cli
Not authenticated	Run olakai login
Network error	Check internet connection, try again

SDK Issues

Problem	Solution
Invalid API key	Verify OLAKAI_API_KEY env var is set correctly
Events not appearing	Check API key matches agent, verify network access
Import errors	Ensure SDK is installed: npm install @olakai/sdk or pip install olakai-sdk

Authentication Issues

Problem	Solution
Browser doesn't open	Copy URL from terminal manually
Login succeeds but CLI says not authenticated	Try olakai logout then olakai login again
Corporate SSO issues	Contact your IT admin about OAuth access

---

Quick Reference

# Check status
which olakai              # CLI installed?
olakai whoami             # Authenticated?
olakai agents list        # Agents exist?

# Setup commands
npm install -g olakai-cli # Install CLI
olakai login              # Authenticate
olakai agents create --name "Name" --with-api-key --json  # Register agent

# SDK installation
npm install @olakai/sdk   # TypeScript
pip install olakai-sdk    # Python

# Verify events
olakai activity list --limit 1 --json
olakai activity get EVENT_ID --json

---

Summary Checklist

• Account created at https://app.olakai.ai/signup?flow=developer&source=claude-code
• CLI installed (npm install -g olakai-cli)
• CLI authenticated (olakai login)
• First agent created with API key
• OLAKAI_API_KEY environment variable set
• SDK installed (@olakai/sdk or olakai-sdk)
• Test event generated and visible in dashboard

Once all boxes are checked, you're ready to build production AI agents with full observability!