Getting Started

Owlmetry is designed to be set up by your coding agent. There are two ways to connect your agent:

• MCP (recommended) — Configure a URL once in your editor. No installation, automatic updates, 52 tools available instantly.
• CLI — Install the @owlmetry/cli npm package. Best for CI/CD, scripts, and human terminal use.

Both paths give your agent the same capabilities. Choose MCP if your editor supports it (Claude Code, Codex, OpenCode, Cursor, VS Code, Claude Desktop, Windsurf, Zed, JetBrains, Cline, Roo Code); choose the CLI for automation pipelines or if you prefer terminal workflows.

You can also set everything up manually if you prefer.

Connect via MCP

If your coding agent supports MCP, this is the fastest path. You need two things: an agent API key and your editor's MCP config.

1. Create an agent key — In the dashboard, go to API Keys > New Key > select 🕶️ Agent > name it > Create > copy the key
2. Add the MCP config — Follow the instructions for your editor in the MCP setup guide
3. Verify — Ask your agent to call the whoami tool

That's it. Your agent now has access to all Owlmetry operations — creating projects, defining metrics, querying events, and building funnels.

Connect via CLI

If your editor doesn't support MCP, or if you need Owlmetry in CI/CD pipelines and shell scripts, install the CLI:

npm install -g @owlmetry/cli

Requires Node.js 20+. Pair the CLI with the companion owlmetry-skills Claude Code plugin marketplace so your agent has the full command reference and SDK integration patterns.

Tell Your Agent to Set Up Owlmetry

Install the Owlmetry skills in Claude Code:

/plugin marketplace add owlmetry/owlmetry-skills
/plugin install owlmetry@owlmetry-skills

Then give your coding agent a prompt like this:

Set up Owlmetry in this project. Load `/owlmetry-cli` to authenticate
and create a project/app, then load `/owlmetry-swift` or `/owlmetry-node`
(depending on the platform) to instrument the code.

That's it. Your agent reads the skills and takes it from there. The only thing you'll need to do is provide a 6-digit verification code — the agent will ask for your email, Owlmetry sends you a code, and you paste it back. This creates your account, generates an API key, and the agent handles the rest: creating a project, setting up an app, installing the SDK, and wiring up event tracking.

Tip: Add this line to your project's CLAUDE.md, AGENTS.md, or whatever default instructions file your coding agent uses:

### Owlmetry
Load `/owlmetry-cli` before running any `owlmetry` CLI commands or doing analytics work — it links to the appropriate SDK skill for your platform.

This ensures every future session knows Owlmetry is integrated and loads the right skill files automatically — including the full API reference, funnel design rules, and lifecycle metric patterns.

Choose Your Deployment

• Hosted — Use the instance at owlmetry.com. No server setup required.
• Self-hosted — Run Owlmetry on your own server. Full control over your data, deployed in under 30 minutes.

Manual Setup

Prefer to set things up yourself? Here's what to do.

1. Sign Up

Go to owlmetry.com and enter your email. You'll receive a 6-digit verification code — enter it to sign in. No password needed. Your account is created automatically on first verification.

If you're self-hosting, use your own instance URL instead.

2. Create a Project

In the dashboard sidebar, go to Projects and click Create Project. A project groups related apps across platforms (e.g., an iOS app and a backend service under one project).

3. Create an App

From your project's detail page, click Create App. Choose the platform that matches your target:

For Apple, Android, and Web platforms, provide a bundle ID (e.g., com.example.myapp). Backend apps don't need one.

When you create the app, a client API key (owl_client_...) is generated automatically. Copy this key — you'll need it to configure the SDK.

4. Install and Configure Your SDK

Swift Quickstart

For iOS, iPadOS, and macOS apps. Requires an Apple-platform app and client key from Owlmetry.

1. Add the Swift Package

In Xcode: File > Add Package Dependencies, enter the repository URL, select branch main, and add Owlmetry to your target.

Or in Package.swift:

dependencies: [
    .package(url: "https://github.com/owlmetry/owlmetry-swift.git", branch: "main")
]

For stable releases, pin to a version instead: .package(url: "…", from: "X.Y.Z"). See releases for the latest.

Add to your target:

.target(name: "YourApp", dependencies: [
    .product(name: "Owlmetry", package: "owlmetry-swift")
])

Minimum platforms: iOS 16.0, macOS 13.0. Zero external dependencies.

2. Configure

Call Owl.configure() as early as possible -- in your @main App init() or AppDelegate didFinishLaunching:

import Owlmetry

@main
struct MyApp: App {
    init() {
        do {
            try Owl.configure(
                endpoint: "https://ingest.owlmetry.com",
                apiKey: "owl_client_your_key_here"
            )
        } catch {
            print("Owlmetry configuration failed: \(error)")
        }
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

3. Log an Event

Owl.info("App launched")
Owl.error("Failed to load profile", screenName: "ProfileView")
Owl.warn("Slow network response", attributes: ["latency_ms": "1200"])

Events are buffered and flushed automatically in batches. They appear in the Owlmetry dashboard within seconds.

Node.js Quickstart

For API servers, job workers, and serverless functions. Requires a backend-platform app and client key from Owlmetry.

1. Install

npm install @owlmetry/node

Zero runtime dependencies. Node.js 20+. Dual ESM and CommonJS builds.

2. Configure

Call Owl.configure() in your main entry point, before any other Owl calls:

import { Owl } from '@owlmetry/node';

Owl.configure({
  endpoint: 'https://ingest.owlmetry.com',
  apiKey: 'owl_client_your_key_here',
  serviceName: 'my-api',
  appVersion: '1.0.0',
});

3. Log an Event

Owl.info('Server started', { port: 4000 });
Owl.error('Database connection failed', { host: 'db.example.com' });
Owl.warn('Rate limit approaching', { current: 95, limit: 100 });

Events are buffered in memory and flushed every 5 seconds or when 20 events accumulate. A beforeExit handler auto-flushes on graceful shutdown.

4. Scoped Logging (Optional)

In multi-user backends, create a scoped logger to automatically tag events with a user ID:

const owl = Owl.withUser('user_42');
owl.info('Order placed', { order_id: 'ord_123' });
owl.error('Payment failed', { reason: 'insufficient_funds' });

What's Next

Once events are flowing, explore these areas:

• MCP -- Connect agents via the Model Context Protocol
• Events -- Understand log levels, sessions, and timestamps
• Metrics -- Track operation durations and success rates
• Funnels -- Measure conversion across multi-step flows
• CLI -- Query and manage everything from the terminal
• API Reference -- Full REST API documentation