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

Two kinds of token

App tokens (onramp_pat_..., minted from an app's Settings > Agent access) can manage that one app - funnels, segments, ingestion keys, and read-only analytics. They can't see or touch any other app.

Project-creation tokens (onramp_org_..., minted from Team) can only create new apps and list existing app names, nothing else. Creating an app returns a fresh app token in the response, so an agent can bootstrap a brand-new project with just this one credential.

Organization-management tokens (onramp_org_..., minted by onramp login) can manage every app in the organization. Pass --app-id <id> for app-specific commands, or use onramp apps list to find the project ID.

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>] [--alerts-enabled true|false] [--alert-slack-webhook-url <url>] [--alert-threshold-pct <n>] [--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 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 team list
onramp billing status
onramp integrations list

--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_org_xxxxxxxxxxxx   # project-creation token

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