CLI
CLI
Manage Owlmetry from the command line — query events, manage projects, and integrate with AI agents.
The Owlmetry CLI (@owlmetry/cli) lets you manage your Owlmetry instance from the terminal. Use it to query events, create and manage projects and apps, inspect metrics and funnels, and view audit logs. Companion agent skills for the CLI and SDKs are distributed separately as the owlmetry-skills Claude Code plugin marketplace.
Key capabilities
- Query events with flexible filters, date ranges, and output formats
- Manage resources — projects, apps, metrics, and funnels
- Inspect metrics — view definitions, query aggregations, and browse raw metric events
- Analyze funnels — run funnel queries with open/closed modes and experiment segmentation
- Triage issues — list, claim, resolve, silence, snooze, merge, and comment on error issues
- Manage integrations — add and sync third-party providers like RevenueCat
- Run background jobs — trigger, watch, and cancel jobs, and browse run history
- Inspect attachments — list, download, and delete event attachments uploaded by SDKs
- List app users — filter by billing tier, anonymous/real, or search by ID
- Audit trail — review who did what across your team
- Multi-team support — authenticate with multiple teams and switch between them with
owlmetry switch - AI agent integration — companion skills for CLI, Node SDK, and Swift SDK via the owlmetry-skills Claude Code plugin marketplace
Command groups
| Command | Purpose |
|---|---|
auth | Send verification codes and exchange them for agent API keys |
setup | Configure the CLI with an existing agent API key |
whoami | Show the authenticated identity and list configured profiles |
switch | List configured team profiles or switch the active one |
projects | List, view, create, and update projects |
apps | List, view, create, and update apps within a project |
events | Query events with filters, time ranges, and pagination |
investigate | Build a breadcrumb timeline around a specific event |
users | List app users with billing-tier and anonymous/real filters |
metrics | Manage metric definitions and query aggregations or raw events |
funnels | Manage funnel definitions and run funnel analytics |
issues | View and manage error issues (resolve, silence, snooze, claim, merge, comment) |
integrations | Manage third-party integrations (e.g. RevenueCat) |
jobs | List, view, trigger, and cancel background jobs |
attachments | List, show, download, and delete event attachments; show project usage |
audit-log | View audit log entries for team actions |
ratings | View per-country App Store rating aggregates (incl. star-only) |
reviews | List, view, and respond to App Store / Play Store reviews |
skills | Print instructions for installing the owlmetry-skills Claude Code plugin marketplace |
Global options
Every command accepts these global flags. They can be placed before or after the subcommand.
owlmetry [global options] <command> [command options]| Flag | Description | Default |
|---|---|---|
--format <format> | Output format: table, json, or log | table |
--endpoint <url> | Owlmetry API server URL | From config or https://api.owlmetry.com |
--api-key <key> | API key (overrides config file) | From config or OWLMETRY_API_KEY env var |
--ingest-endpoint <url> | Ingest endpoint URL (for SDK setup commands) | Derived from API endpoint |
--team <name-or-id> | Use a specific team profile for this command | Active team from config |
--version | Print CLI version | |
--help | Show help for any command |
Configuration resolution
The CLI resolves configuration in this order:
- Command-line flags (
--endpoint,--api-key,--team) - Environment variables (
OWLMETRY_ENDPOINT,OWLMETRY_API_KEY) - Config file (
~/.owlmetry/config.json)
See Authentication for details on setting up the config file.
Output formats
The --format flag controls how results are displayed:
table(default) — human-readable tables with aligned columnsjson— raw JSON, suitable for piping tojqor other toolslog— chronological log view, used byeventsandinvestigatecommands
# Default table output
owlmetry events --since 1h
# JSON for scripting
owlmetry events --since 1h --format json
# Log view for event streams
owlmetry events --since 1h --format log