Connect Your App

App addressCopy Anchor Link

Open Setup → App address and enter the URL customers use to access your app. Include the protocol, for example https://app.example.com. Add localhost only when you also need local development. Use Edit to update an existing address.

Save the address, then open Environment values. Create each missing credential independently. Working values stay active when you create a replacement.

Environment valuesCopy Anchor Link

All four values are required for guided setup. Choose your framework in Setup to see the right names. For Next.js:

Discovery key: SAASFUNNELS_API_KEY belongs in the same configuration list, but only your installer needs it. Load it into the local terminal or CI process that runs discovery. Do not expose it to the browser or add it to the deployed app just for setup.

The developer setup key has only developer:read and features:write. It can submit findings for review; it cannot approve mappings, manage the payment connection, or verify payments.

Save local values in your normal secrets workflow, such as an uncommitted .env.local. Save deployment values in the matching hosting environment or secret-manager configuration, then restart or redeploy. The CLI process also needs its developer key loaded into its environment.

SaaSFunnels cannot inspect Doppler or your hosting configuration. Copied, Connection saved, and Verified mean different things. Verification requires evidence from your running application.

Keys are shown only when created. Returning to Setup shows Created. Retrieve saved values from your secret manager. If a key was lost, use its refresh icon to open the replacement confirmation. Save the replacement in the appropriate destination, and revoke unused credentials in Settings.

Values ready means all required credentials exist. Creating the final missing key updates this status automatically. Copying a name or value does not change it, and there is no manual completion button. It does not mean SaaSFunnels has checked your local files, secret manager, or hosting configuration. A non-administrator may need an administrator to check or create the discovery key.

Copy available environment entries copies only the available app values. Use the discovery row's copy control for its local/CI entry. Neither control copies placeholders as working values.

Install and deployCopy Anchor Link

Choose Copy installation instructions in Install and deploy. Paste them into the selected coding agent in your application repository, or give them to your developer. The agent must carry out the instructions; copying them does not start an installation. The expandable Install from your terminal (optional) command prepares the same developer tools. Skip it if your coding agent follows the copied instructions; running the command alone does not connect or deploy the app.

The installation instructions include:

• Installing the supported browser runtime.
• Issuing short-lived runtime sessions from your authenticated backend, using trusted account and user identity.
• Running feature, plan, and branch discovery with the CLI and reviewing its findings.
• Implementing payment actions in your existing backend, configuring secrets, and deploying.

The installation prompt contains configuration names and placeholders, not credentials. For a manual implementation, use the same handoff and runtime contracts.

The Install and deploy step becomes Verified automatically when SaaSFunnels receives app activity and verifies a signed-in identity. Deploy and visit your app while signed in. Copying instructions or generating keys does not verify installation.

Discover and review features and plansCopy Anchor Link

Discovery commands, retries, and plan review are in Setup → Funnel setup → Features & Plans. If the installation instructions already completed discovery, review those results without repeating the scan. A successful scan with no findings counts. A scan that never ran, failed, or was interrupted does not.

Run discovery in Review and verify opens Funnel setup → Features & Plans. Run this from your application repository; no separate CLI installation is required:

npx --yes saasfunnels@latest setup run

If you use Doppler, select Doppler to copy:

doppler run -- npx --yes saasfunnels@latest setup run

Use the Doppler project/config containing your discovery key. If the key is not loaded, the guided command asks whether to read it from this folder’s Doppler configuration or .env.local, or shows where to create it.

The preparation command (npm install, saasfunnels init, and saasfunnels agent install) only installs tools and writes local instructions. It does not implement your app integration or start discovery. The full preparation command is included in the copied installation instructions.

Install and deploy shows App connected and Signed-in identity verified as evidence arrives. Features & Plans shows discovery progress independently. Keep the terminal open while discovery runs. Choose Review findings when proposals arrive. An empty supported scan needs no findings review, but reported coverage gaps still need a developer's review.

Approve structured discovery uploads when prompted. For an already approved non-interactive CI run, add --send. Use --resume after an interruption. The CLI does not implement arbitrary billing code or automatically accept feature mappings.

In Review findings, review the prefilled features, plans, and limits. The compact Decisions dialog lists any missing measurements, included allowances, or access choices. Expand a row to answer it and save. Decisions remains in the plans header so you can reopen and change saved answers. When ready, choose Publish configuration. Confirm publishing in the short modal, or choose Back to keep editing. Proposed discovery exclusions are available there as optional details. Publication automatically verifies covered findings; there is no second per-feature confirmation. The full Plans & pricing editor remains available when needed.

Discovery also flags application languages it cannot scan, dynamic entitlement checks, and optional commercial structures such as add-ons, capacity bands, and trials. Ask your developer to review those parts of the app and configure any relevant access before marking the review complete. Discovery does not guess their meaning. Discovery coverage explains the supported patterns and recovery paths.

If pricing extraction needs developer review, .saasfunnels/setup-review.json names the exact files and reasons. Correct those declarations, or create .saasfunnels/setup-pricing.json with reviewed literal mappings, then run a fresh scan:

{
  "plans": [
    {
      "key": "pro",
      "name": "Pro",
      "features": { "export": true, "seats": 5 },
      "prices": [{ "key": "price_REPLACE_WITH_REAL_ID" }]
    }
  ]
}

Use actual price IDs from the connected merchant. A limit can be a nonnegative number or "unlimited". Static TypeScript plan tables can also use capability maps, quota maps, literal spreads, and Stripe lookup keys; lookup keys must match exactly one price in the connected catalog. Missing feature evidence is not interpreted as exclusion. No raw pricing source is uploaded.

Event coverage and other credentialsCopy Anchor Link

Review activation, useful feature usage, blocked paid features, plan/usage limits, upgrade/checkout intent, cancellation and downgrade intent, trial lifecycle, billing health, team growth, and integration/support friction. A short list of sample events is a starting point, not proof of complete coverage.

The event-discovery skill covers event instrumentation. Feature/plan discovery, runtime installation, payments, and ongoing CI checks are separate parts of the full installation instructions. Discovery finds static definitions and proposes mappings; it does not automatically add runtime event calls or authorize features.

Reuse connected Stripe billing and trial facts. Capture actual blocked feature attempts from the app's existing entitlement decision; do not confuse security/role restrictions with paid-plan gates. Trial-ending notifications need an authoritative provider event or scheduled backend check. Avoid duplicating the same outcome across sources.

If additional backend events need Direct API delivery, its separate SAASFUNNELS_INGEST_API_KEY comes from Settings → Integrations → Direct API. It is server-only and conditional; it is not the discovery key or Funnel server key.

Local work, deployment, and ongoing syncCopy Anchor Link

Local discovery can scan uncommitted work in an existing Git repository with a commit and an origin remote. No production push is required to discover and submit findings. Installing the CLI, initializing it, and installing agent instructions do not ask setup questions. setup run asks where your developer key is saved when it is not loaded, then asks permission before uploading findings; features setup has a separate local review flow.

A running app is required to verify browser activity, signed-in identity, and payment handling. Local or preview verification requires matching allowed origins and connection configuration. Deploy through your normal release process when you are ready to install the changes for customers.

GitHub automation requires a committed/pushed workflow and correctly scoped secrets. The current installer does not add it automatically, and the current catalog drift Action uploads an existing manifest rather than freshly scanning source. See CI Event Validation for the current requirements and limitations.

Connect payments and reviewCopy Anchor Link

Stripe authorization imports billing context. Your application still handles payment requests and verified outcomes. Reuse an existing suitable Stripe webhook where possible; preserve its billing behavior and existing event subscriptions. Create a new endpoint only when necessary. Verify Payments covers the required events and secrets.

An administrator saves the payment endpoint and two distinct signing secrets together in Payment connection. Checks then run automatically. Connection checks never charge customers.

Deploy and visit the app while signed in. Review discovery findings under Funnel setup → Features & Plans, then return to Review and verify for any remaining checks. Create your first Funnel after Installation verified appears, then test the actual Funnel and Stripe test-payment journeys before publishing.

Review and publish discovered configurationCopy Anchor Link

CLI 0.4.x sends supported plan access, quota measurement, and add-on evidence to Review your plans. Known settings are prefilled. Resolve specific missing facts and conflicting values, then publish from the review. A short confirmation opens before publication; it does not repeat the configuration grid. A successful publication automatically completes the covered review items. Configuration publication does not implement usage reporting, change billing code, or certify a payment.

Use Copy developer questions for unresolved application behavior. Put corrected normalized declarations in .saasfunnels/setup-pricing.json and bounded question explanations in .saasfunnels/setup-answers.json. Run npx --yes saasfunnels@latest setup run after changing either file. Use --resume only for unchanged interrupted work.