CLI

@onramp-sdk/cli lets a coding agent (or a human) create apps, manage funnels and saved segments, and read analytics from a terminal - everything the dashboard can do except delete anything. There is no delete command anywhere in the CLI; destructive actions stay in the dashboard, gated behind a typed confirmation.

Works the same way on macOS, Linux, and Windows - it's a plain Node.js CLI with no OS-specific setup.

Installation

bash

npm install -g @onramp-sdk/cli
# or run it without installing
npx @onramp-sdk/cli --help

Requires Node.js 18 or later.

Authentication

The CLI reads its token from, in order: the --token flag, the ONRAMP_TOKEN environment variable, then a stored credentials file (~/.onramp/credentials.json on macOS/Linux, %USERPROFILE%\.onramp\credentials.json on Windows).

For a coding agent or CI, set the environment variable - no interactive step required:

bash

export ONRAMP_TOKEN=onramp_pat_xxxxxxxxxxxx
onramp whoami

For a human at a terminal, onramp login opens your browser, signs you in with your existing OnRamp account, and authorizes the CLI for your organization. The resulting organization token is stored locally:

bash

onramp login
# Or store an existing token explicitly:
onramp login --token onramp_pat_xxxxxxxxxxxx

Tokens

Mint tokens from Team. Each token is scoped to the projects you pick (or every project) and a mix of read/write per resource (funnels, segments, ingestion keys, integrations, app settings — insights, team, and billing are always read-only). New tokens default to read-only until write is enabled per resource. You can change a token's projects and permissions later from Team without rotating the secret. Pass --app-id <id> for app-specific commands whenever a token covers more than one app, or use onramp apps list to find the project ID.

A token granted access to every project can also create new apps. Two flows mint a full-access token automatically rather than going through the picker: onramp login (every project) and onramp apps create (just the new app, so the CLI can create funnels on it immediately).

Output

Output is JSON by default, since the primary audience is a script or an agent parsing the result. Pass --pretty for a human-readable rendering instead.

bash

onramp funnels list --pretty

Commands

bash

onramp login [--token <token>]
onramp whoami

onramp apps create --name <name> [--platform react_native|ios|android|flutter|web] [--website-url <url>]
onramp apps list
onramp apps get [--app-id <id>]
onramp apps update [--app-id <id>] [--name <newName>] [--digest-enabled true|false]

onramp funnels create --name <name> --steps <json-or-@file>
onramp funnels update <funnelName> [--name <newName>] --steps <json-or-@file>
onramp funnels list
onramp funnels get <funnelName>

onramp segments create --name <name> [--filters <json-or-@file>]
onramp segments update <segmentName> [--name <newName>] [--filters <json-or-@file>]
onramp segments list
onramp segments get <segmentName>

onramp keys create
onramp keys list
onramp keys revoke <keyId>

onramp insights overview --start <iso> --end <iso>
onramp insights metrics --start <iso> --end <iso> [--currency <code>]
onramp insights acquisition --start <iso> --end <iso> [--currency <code>]
onramp insights funnels --start <iso> --end <iso>
onramp insights breakdown <funnelName> --start <iso> --end <iso>
onramp insights retention [funnelName] --start <iso> --end <iso>
onramp insights dropoff <funnelName> --step-name <s> --next-step <s> --start <iso> --end <iso>
onramp insights exit-paths <funnelName> --step-name <s> --next-step <s> --start <iso> --end <iso>
onramp insights ai <funnelName> [--start <iso>] [--end <iso>]
onramp insights user (--anonymous-id <id> | --user-id <id> | --email <email>) --start <iso> --end <iso>
onramp insights conversion --from <event> --to <event> --start <iso> --end <iso>
onramp insights property <key> [--event <name>] --start <iso> --end <iso>

onramp team list
onramp billing status
onramp integrations list
onramp integrations connect --provider stripe|revenuecat|paddle|lemonsqueezy --credentials <json-or-@file> [--identity-strategy email|anonymous_id|property] [--identity-property <name>] [--sync-frequency-hours <n>]

Google Ads and Search Console aren't connectable this way

integrations connect only covers the credential-paste providers (Stripe, RevenueCat, Paddle, LemonSqueezy) - those just need a secret key, so a single request is enough. Google Ads and Google Search Console require a real OAuth consent-screen redirect, which can't be completed headlessly from a CLI; connect those from the dashboard's Integrations tab instead.

insights metrics returns every metric available on the project in one JSON response: product traffic, sessions, events and engagement, subscription revenue and churn, blended advertising performance, Google Ads, Apple Search Ads, Meta Ads and TikTok Ads performance, directly attributed revenue, impressions, CTR, CPC, CPM, CPA, CPI, CAC, ROAS, net ROAS, LTV:CAC, payback, and configured custom property metrics. It also includes daily series and converts integration money into the project display currency using the same ECB rates as the dashboard.

insights acquisition returns campaign visitors, milestones, paid conversions, spend, revenue, clicks, impressions, paid CAC and ROAS alongside Search Console, AI-referral, crawler, and revenue-aware attribution breakdowns.

insights breakdown and insights exit-paths also include appVersion/platform/osVersion conversion breakdowns and per-destination time-to-arrival stats (median/p90 seconds plus a <10s/10s-2m/2m-1h/1h-24h/>24h histogram) respectively - useful for telling a genuine UI dead-end (a two-second gap) apart from a killed-app-then-restart (a multi-hour gap).

insights breakdown, insights overview, and insights user also return utmMedium/utm_medium - the signal that actually separates a paid click from organic Play/App Store discovery when utmSource alone is ambiguous (a Google Ads install and an organic Play Store listing can both carry utm_source=google; only the ad-driven one carries utm_medium=cpc).

insights user pulls one person's full ordered event timeline by our own anonymous_id, or by the customer's own userId/email trait passed to identify() - exactly one of --anonymous-id, --user-id, or --email is required. This is quota-gated like insights dropoff.

insights conversion computes a two-event conversion rate on the fly - no funnels create step required first, so brand-new instrumentation can be sanity-checked the moment it starts landing.

insights property aggregates a custom event property (count/sum/avg/min/max/p50/p90) across a date range, scoped to one event via --event or app-wide without it - no metric configuration needed first.

Every insights subcommand also accepts --last <duration> (e.g. 24h, 30d, 2w) as a shorthand for --start/--end - they're mutually exclusive.

--app-id can be omitted on any app-scoped command when you're using an app token - it's resolved automatically from the token itself.

Flags that take JSON (--steps, --filters) accept either an inline JSON string or @path/to/file.json - useful when an agent is composing a multi-step funnel definition.

Example: bootstrap a new project end to end

bash

export ONRAMP_TOKEN=onramp_pat_xxxxxxxxxxxx   # Team token with access to every project

APP_TOKEN=$(onramp apps create --name "My App" --platform ios | node -pe 'JSON.parse(require("fs").readFileSync(0)).managementToken')
export ONRAMP_TOKEN="$APP_TOKEN"              # switch to the new app's own token

onramp funnels create --name Activation --steps '[
  {"step_name":"app_opened","display_label":"App opened"},
  {"step_name":"signed_up","display_label":"Signed up"}
]'

onramp segments create --name "US users" --filters '{"country":"US"}'
onramp insights funnels --start 2026-07-01T00:00:00Z --end 2026-08-01T00:00:00Z