SaaSFunnels CLI

Initialize local config, validate event payloads, send Direct API smoke events, and run setup diagnostics from a terminal.

The SaaSFunnels CLI is the human and CI setup path. Use it to generate examples, validate payloads, send one safe Direct API smoke event, and run diagnostics before routing revenue signals.

Test the release candidate

Before the public prerelease, build and pack the existing package owner from the repository:

npm --prefix packages/prevenue run build
npm pack ./packages/prevenue
npm install --global ./saasfunnels-0.1.0-beta.0.tgz
saasfunnels verify --json

The tarball installs only the saasfunnels executable. The package remains private until final-host certification and trusted publication.

Initialize local config

Create a project-local config file for non-secret defaults:

saasfunnels init --api-base-url https://app.prevenue.ai

The config does not store API keys. Keep secrets in environment variables or your existing secret manager.

Use SAASFUNNELS_API_BASE_URL only for non-production or staging-safe checks:

export SAASFUNNELS_API_BASE_URL=https://app.prevenue.ai

app.prevenue.ai is the controlled pre-rename test host. The public default changes once to app.saasfunnels.ai during the coordinated cutover; the commands and output contract stay the same.

Verify an installation

Run the stable verification entry after installation or in CI:

saasfunnels verify --json
saasfunnels verify --event ./saasfunnels-event.json --catalog ./.saasfunnels/catalog.yaml --json
SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> saasfunnels verify --live --json

Without --live, verification checks all built-in source contracts locally and reports that live checks were skipped. --event and --catalog add project fixtures. --live checks the authenticated workspace, integrations, and readiness through customer-safe APIs.

Exit codes are stable:

Code	Meaning
`0`	Every requested check passed.
`1`	A local event or catalog validation failed.
`2`	Configuration, authentication, network, or live-service verification could not run successfully.

Generate sample payloads

Print source-specific sample payloads and requirements:

saasfunnels events sample --source direct
saasfunnels events sample --source posthog --json
saasfunnels events sample --source segment --json

Use Direct API for backend source-of-truth events, PostHog or Segment for selected existing pipeline events, Web SDK for browser-visible intent, and Stripe for billing truth.

Validate event payloads

Validate a local JSON payload before shipping it:

saasfunnels events validate ./saasfunnels-event.json --source direct
saasfunnels events validate ./posthog-event.json --source posthog --json
saasfunnels events validate ./segment-event.json --source segment --json

Validation reports:

Missing account identity.
Invalid semantic types.
Oversized or unsafe event names.
Token-like or email-like unsafe fields.
Missing stable idempotency keys.
Non-revenue-relevant payload warnings.
Signal-family mapping hints.

In CI, use --json and fail the job when the command exits non-zero.

Send a setup smoke event

Send one safe Direct API test event:

SAASFUNNELS_INGEST_API_KEY=<SAASFUNNELS_INGEST_KEY> saasfunnels events send-test --json

Or send a file:

SAASFUNNELS_INGEST_API_KEY=<SAASFUNNELS_INGEST_KEY> saasfunnels events send-test --file ./saasfunnels-event.json --json

The output summarizes whether the event was accepted, rejected, duplicated, persisted, and queued for workflow processing. It should never print the full ingest key.

Run diagnostics

Use doctor for source setup, event health, mappings, destinations, and recent signal checks:

SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> saasfunnels doctor
SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> saasfunnels doctor --events --mappings --json

Use readiness for signal-family readiness rows:

SAASFUNNELS_API_KEY=<DEVELOPER_READ_KEY> saasfunnels readiness --json

Common fixes:

Symptom	Fix
Missing account identity	Add `account_id`, PostHog account/group properties, or Segment `groupId`.
Wrong or revoked key scope	Use `developer:read` for diagnostics and `direct:write` or `events:write` for smoke sends.
Event is diagnostic-only	Send a custom product or revenue event instead of provider/system test events.
Mapping gaps remain	Review Events and confirm semantic mappings for high-signal event families.
Destination not ready	Connect Slack, webhook, or another destination after signal evidence looks useful.

On this page