SaaSFunnels CLI
Initialize local config, validate event payloads, send Direct API smoke events, and run setup diagnostics from a terminal.
Use the guided command to discover your application's features and plans and send proposals to Setup for review. Requires Node.js 22 or newer.
Start guided discovery
Run this in your application's Git repository:
npx --yes saasfunnels@latest setupNo separate package installation is required. @latest avoids an older project-local CLI. setup run is an equivalent command.
If SAASFUNNELS_API_KEY is not loaded, choose where you saved it: Doppler for this folder's configured project, .env.local, or I haven't saved it yet for instructions. Get the discovery key from Setup → Environment values. The CLI reads that key without printing it or loading unrelated values from the file.
The command checks your connection, asks before uploading findings, scans features and pricing, and reports progress to Setup. Return to Funnel setup → Features & Plans → Review findings to review the proposals. Nothing is automatically approved.
Resume interrupted work with:
npx --yes saasfunnels@latest setup run --resumeIf the source code or connected workspace changed, start again without --resume. Already accepted stages are reused for an unchanged run.
For an explicit local file, use --env-file .env.local. For Doppler, you can also run:
doppler run -- npx --yes saasfunnels@latest setupFor CI, load SAASFUNNELS_API_KEY from its secret store and use --send --non-interactive only after approving the structured upload. npm's --yes accepts package installation; it does not approve discovery uploads.
Install local tools and agent instructions
The guided discovery command does not implement or deploy your application integration. Use Install and deploy → Copy installation instructions for your developer or coding agent. Connect Your App covers runtime configuration, signed-in identity, discovery, and verification.
If you want the CLI saved as a project dependency, or need to prepare coding-agent instructions:
npm install --save-dev saasfunnels@latest
npx saasfunnels init
npx saasfunnels agent install --target codexUse claude-code, cursor, or markdown instead of codex for another handoff format. These preparation commands do not run discovery. They also do not start a coding agent or create a GitHub workflow.
The advanced command reference below uses saasfunnels for a global installation. With a project-local installation, prefix those commands with npx. The CLI repository contains the source and release workflow.
Initialize local config
Create a project-local config file for non-secret defaults:
saasfunnels initThe config does not store API keys. Keep secrets in environment variables or your existing secret manager.
The CLI defaults to https://app.saasfunnels.ai. Use --api-base-url or SAASFUNNELS_API_BASE_URL only when you intentionally target localhost, a preview, or a controlled rollback host.
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 verify --live --jsonWithout --live, verification checks all built-in source contracts locally and reports that live checks were skipped. --event and --catalog add project fixtures. Set SAASFUNNELS_API_KEY to a developer:read key before --live; it checks the authenticated workspace, integrations, and readiness through customer-safe APIs. API Keys and Scopes shows a shell-safe way to enter the key.
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. Copy the sample_payload from JSON output into a local file when using events validate or verify --event:
saasfunnels events sample --source direct
saasfunnels events sample --source posthog --json
saasfunnels events sample --source segment --jsonUse 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 --jsonValidation 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
Set SAASFUNNELS_INGEST_API_KEY from a secret manager or use the shell-safe prompt, then send one safe Direct API test event:
saasfunnels events send-test --jsonOr send a file:
saasfunnels events send-test --file ./saasfunnels-event.json --jsonThe 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 doctor
saasfunnels doctor --events --mappings --jsonUse readiness for signal-family readiness rows:
saasfunnels readiness --jsonSet SAASFUNNELS_API_KEY to a developer:read key before running diagnostics or readiness checks.
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. |
Discover Features and plans
The CLI can inspect local project files and propose a Feature catalog or plan sources. Discovery is local; review the proposed files before applying or sending anything:
saasfunnels features setup --json
saasfunnels plans discover --json--apply writes the reviewed local manifest. The separate features handoff --send and plans handoff --send commands transmit the approved handoff to your SaaSFunnels workspace. See saasfunnels --help for required repository and integration identifiers.
Related articles
Guided installation discovery
Installing the package, running init, and running agent install only prepare local tools and instructions. They do not start a coding agent, implement the app integration, or run discovery. Paste Copy installation instructions into your coding agent to perform the full implementation.
Run npx --yes saasfunnels@latest setup run or resume with npx --yes saasfunnels@latest setup run --resume. Use the discovery key from Setup → Environment values (developer:read, features:write) through SAASFUNNELS_API_KEY in your local environment or CI. The server resolves workspace, Stripe integration, and environment; the command does not ask you to choose a separate test/live workspace.
The command scans features, waits for catalog import, extracts normalized pricing evidence locally, and scans plan branches. It requests permission before uploading structured findings; --send records explicit approval for a non-interactive invocation. Accepted stages are not submitted again when resuming. Progress files contain repository identity and run context only, never credentials.
When pricing needs developer review, .saasfunnels/setup-review.json names the exact files and reasons. Correct those declarations or provide a reviewed .saasfunnels/setup-pricing.json declaration. See Connect Your App for its format. The pricing handoff also uses developer authentication and submits normalized evidence instead of raw source files. Existing browser-based imports remain available.
Review accuracy and coverage
Discovery reads supported JavaScript/TypeScript checks and static plan catalogs in JavaScript, TypeScript, JSON, or YAML. It excludes recognized tests, fixtures, demo scopes, comments, and unrelated role permissions. It can propose capabilities and numeric or unlimited quotas. It reads explicit quota measurement declarations but never guesses missing units, reset periods, or aggregation. It does not execute application code.
In Review findings, plans and feature access are prefilled from supported evidence. Resolve the highlighted questions about units, reset periods, mapping choices, or conflicts. Inspect add-ons and included allowances, then select Publish configuration. A short publish confirmation keeps any proposed discovery exclusions available as optional details. Choose Back to return to editing. Publication verifies the approved configuration and resolves its findings automatically.
Use Decisions in the plans header to revisit saved answers. Expand any row to edit it and save once. Back to plans returns to the table without losing unfinished inputs. Keep existing preserves a configured value; it does not discard the comparison. An unsupported requirement remains open until it is corrected or established as irrelevant.
For developer questions, inspect the referenced application behavior and put corrected normalized plans in .saasfunnels/setup-pricing.json. The file accepts explicit quotas and components alongside features and prices. For each quota, provide unit, period, aggregation, and usageSource: "customer_reported". Its numeric or "unlimited" access belongs in features.
Recurring components identify their exact Stripe product and prices, required, relatedFeatureKey, includedQuantity, quantitySourceKey, and quantityBasis ("total" or "additional"). With 10 included members and 12 total members, only 2 are additional. If the application already reports 2 additional members, the allowance must not be subtracted again. These declarations describe configuration; they do not implement usage reporting or billing.
Developer explanations go in .saasfunnels/setup-answers.json as an array of { id, fingerprint, disposition, reason }, using the question identity supplied by Setup. disposition is configuration, not_applicable, or unresolved; corrected configuration belongs in the pricing file. A configuration answer also includes configuration: [{planKey, featureKey}] or [{planKey, componentKey}] referencing those declarations. Required unsupported behavior must remain unresolved. Explanations remain subject to administrator review. Do not include source content or credentials.
Run a fresh npx --yes saasfunnels@latest setup run after changing either reviewed file. Resume only an unchanged interrupted run. The application and CLI require the same Setup contract; this flow requires CLI 0.4.x.
Pricing imports and arbitrary dynamic helpers that cannot be resolved statically need a reviewed literal declaration or manual configuration. Finding no supported checks is not proof that an application has no features. Supported empty scans are distinct from incomplete scans and coverage tasks awaiting review.
A new scanner version or source change can require a fresh run without --resume. Completed evidence and human decisions are preserved; local generated catalogs are not overwritten by guided discovery. Failed or partial runs do not replace the last completed review set.
Discovery cannot approve mappings, configure payment connections, or certify payments. Review findings in Setup. Skipped or failed scans do not complete setup.