Skip to content
RevTurbine Docs

Add RevTurbine with a Coding Agent

If you integrate through a coding agent, you don’t have to hand-wire anything. Pick the prompt that matches your situation — adding RevTurbine to an app you already have, or building a new app with RevTurbine from the start. The agent does the inspection and the edits, and you review the diff.

Existing app: replace one plan check

Section titled “Existing app: replace one plan check”
You're adding RevTurbine (@revturbine/sdk) to this app to gate one paid feature.


1. Inspect the app and find ONE non-critical feature currently gated by a
   hard-coded plan check (e.g. `user.plan === 'pro'`). Pick the safest one.
2. Run `npm create revturbine@latest`. It installs @revturbine/sdk, pins the CLI
   and writes a starter revturbine.playbook.json. Wrap the app in
   <RevTurbineProvider> in local_only mode with that Playbook, so it runs with no
   account.
3. Edit the Playbook so it has a free and a pro plan, one entitlement for the
   feature, and a gate placement (upgrade modal) for free users. Refer to plans and
   entitlements by their unique_handle. Run
   `npx revturbine validate ./revturbine.playbook.json` until it reports no errors
   or warnings.
4. Replace the hard-coded check with <Gate id="..." can="<entitlement>">, keeping
   the existing UI as the gated children and letting the placement render the upsell.
5. Do NOT touch any billing-critical or server-side enforcement path. Leave those
   checks in place — the client Gate is UI only.
6. Run the type checker, then explain the diff: what moved into config, what stayed
   in code, and why the server-side check (if any) was left alone.

New app: build RevTurbine in from the start

Section titled “New app: build RevTurbine in from the start”
You're building a new app with RevTurbine (@revturbine/sdk) handling its plans,
entitlements, usage limits and upgrade prompts.


1. Scaffold the app with its framework first (e.g. create-next-app), then run
   `npm create revturbine@latest` inside it. It installs the SDK, pins the CLI,
   writes a starter revturbine.playbook.json and installs the RevTurbine agent
   skills. Follow the revturbine-start-here skill.
2. Put monetization in the Playbook, not in code: every plan, entitlement, usage
   limit and upgrade or sign-in prompt. No plan names, prices or limit numbers in
   app code. Build on the starter Playbook and refer to plans and entitlements by
   their unique_handle.
3. Run `npx revturbine validate ./revturbine.playbook.json` after every Playbook
   change and fix every error and warning.
4. Start in local_only mode with the bundled Playbook. Use <Gate> or can() for
   access, <Slot> for prompts, and update() to report usage as the running total
   for the current period (your app keeps that count).
5. Re-check every paid or billable action on the server with
   @revturbine/sdk/headless before it runs, and answer a denial with 402. Client
   checks only drive the UI.
6. If people can use the app before signing in, give them a stable id your server
   can see (for example a cookie) and pass it as user.id.
7. When the docs don't cover something you need, say so and ask. Don't guess.
8. Run `npx revturbine generate types ./revturbine.playbook.json --out
   src/revturbine-handles.ts` and the type checker, then explain what lives in
   the Playbook, what lives in code, and what's left for hosted mode.

Automate the config loop with the CLI

Section titled “Automate the config loop with the CLI”

Everything RevTurbine decides lives in the Playbook, and the CLI (@revturbine/cli, command revturbine) manages the Playbook lifecycle from the terminal — so a customer’s own agent can enhance monetization on a cadence with deterministic guardrails. Anything you can do in the dashboard, you can do through the CLI.

A recurring loop looks like:

Terminal window
# 1. Your agent proposes a config change (new segment, adjusted limit, new copy).
# 2. Validate it against the real schema before anything ships.
revturbine validate ./revturbine.playbook.json


# 3. Upload it as the open draft, then preview and evaluate that draft.
revturbine upload ./revturbine.playbook.json
revturbine preview
revturbine evaluate --draft --user ./user-context.json --entitlement data_export


# 4. Launch it through the review lifecycle.
revturbine launch --draft

The guardrails are the point: the agent proposes, the CLI validates against its pinned schema and lets you preview the impact before launch, and the draft becomes a Release through the same guarded lifecycle a human uses. Your app code never changes — the agent only ever edits the Playbook.

Section titled “Related”