vibemonetize (CLI)

npx vibemonetize wraps an existing Next.js (App Router) or Vite + React app in VibeMonetize in a few commands, without ever requiring the dashboard: wire the SDK into your code, get a developer account and API keys from the terminal, and provision an App with its Features/Meters/Plans — all from one CLI.

Zero runtime dependencies. init never touches the network; signup, app create, bundle create, grant, and doctor's remote checks do.

Install & run

npx vibemonetize init

Run it from the root of your project (next to package.json). Pass a directory to target a different project: npx vibemonetize init ./apps/my-app.

No developer account yet? Get one from the terminal:

npx vibemonetize signup --email you@example.com          # emails a 6-digit code
npx vibemonetize signup --email you@example.com --code 123456

Then provision an app:

npx vibemonetize app create --secret-key sk_... \
  --feature pro --meter exports=20 --plan "Pro" --price 900

vibemonetize init

Detects your framework and wires the SDK in. Safe to run more than once — every step only fills in what's missing; it never duplicates or clobbers hand edits.

Framework detection

What it writes

  1. Adds @vibemonetize/react and @vibemonetize/server to package.json.
  2. Wraps your app root in <MonetizeProvider>:
    • Next.js — generates app/providers.tsx (a "use client" boundary) and renders it from app/layout.tsx. An existing providers.tsx has its {children} wrapped in place rather than being replaced.
    • Vite — wraps whatever is passed to .render(...) in src/main.tsx.
  3. Writes .env.local (gitignored placeholders) and .env.example (documents the required shape) with the client vars (NEXT_PUBLIC_/VITE_-prefixed VIBEMONETIZE_APP_ID, _API_URL, _PUBLISHABLE_KEY, _TEST_PUBLISHABLE_KEY) and, for Next.js, the unprefixed server vars @vibemonetize/server reads by default (VIBEMONETIZE_SECRET_KEY, VIBEMONETIZE_TEST_SECRET_KEY). See "Env vars" below for the full list.
  4. If no Tailwind is detected, adds import "@vibemonetize/react/styles.css"; so components render styled with zero build step.
  5. Drops a starter components/VibemonetizeExample.tsx using <Paywall>, <UsageBadge>, and <CheckoutButton> — delete it once you've built your own paywall.
  6. Adds @vibemonetize/seo and drops an SEO starter (for Next.js: app/sitemap.ts/app/robots.ts; for Vite: static public/sitemap.xml/public/robots.txt).
  7. Writes/regenerates MONETIZE.md describing the integration — this one file is intentionally always regenerated (everything else above is additive-only).

Flags

Idempotency: re-running init against an already-wired project only fills in whatever's still missing. It never spawns a package manager or makes a network call — it edits files on disk and tells you the one install command to run afterward.

vibemonetize signup

Gets a developer account and API keys from the terminal, no dashboard needed. Two invocations, no interactive prompts:

npx vibemonetize signup --email you@example.com          # sends a 6-digit code by email
npx vibemonetize signup --email you@example.com --code 123456   # verifies + mints keys

Mints a test-mode key pair (sk_test_/pk_test_) by default, so the first thing you can do with it is exercise the whole paywall → checkout → entitlement loop with zero real charges. Writes the keys into the target directory's .env.local (or prints them if no Next.js/Vite project is detected there) — never echoed to the terminal once written to disk.

Flags

vibemonetize app create

Given a developer secret key, provisions an App (and, optionally, Features/Meters/one-or-more Plans/a publishable key) via the Monetization API and writes the resulting ids straight into .env.local/.env.example — no hand-copying ids out of the dashboard. Safe to run more than once: a rerun reuses whatever's already provisioned instead of duplicating it.

Flags

Credit packs (--interval credits): a --plan's --cap <meterSlug>=<cap> is written with a credit reset period instead of the usual monthly one whenever that plan's own --interval is credits. Entitlement resolution takes the maximum cap across a meter's month/day/ lifetime limits, but sums across its credit limits — so a credit-period cap is what makes a purchased pack an additive top-up (it stacks on top of a subscription's cap, and two packs sum with each other) instead of a second ceiling that just gets maxed away. Every other --interval is unaffected.

Example — free/pro/yearly in one run:

vibemonetize app create --secret-key sk_... --feature pro \
  --meter exports \
  --plan Free --cap exports=5 \
  --plan "Pro Monthly" --slug pro-monthly --price 900 --interval month \
  --plan "Pro Yearly" --slug pro-yearly --price 9000 --interval year

vibemonetize bundle create

Provisions a developer-scoped Bundle (a Plan container with cross-app grants) and, optionally, one Bundle Plan spanning two or more of your apps' Features/Meters. Idempotent like app create: a rerun with the same --name/--plan reuses what already exists. Works with an sk_... key; no directory scaffolding (a bundle isn't tied to one app's env files, so nothing is written to disk).

Flags

Example — a bundle plan spanning two apps' "pro" feature:

vibemonetize bundle create --secret-key sk_... --name "All Apps" \
  --plan "All Access" --price 1900 --interval month \
  --grant <appOneId>:pro --grant <appTwoId>:pro

vibemonetize grant

Comps a plan to an end user by email — the fast way to prove a locked feature unlocks, with no Stripe checkout or browser needed. Creates a comp membership in your key's mode; with the default sk_test_ key it's invisible to live traffic. Sign in as that email in your app and watch the gate open.

Flags

vibemonetize doctor

Verifies the integration end to end and prints the exact fix for anything broken. Local checks (framework detection, SDK dependencies, <MonetizeProvider> wiring, env vars, no secret key sitting in a client-bundled var, Tailwind/styles coverage) are always offline. Remote checks (API reachability, key validity, that a plan exists to sell, and how far the checkout funnel has actually fired) run only when an API URL and keys are configured, and degrade to skipped — never failed — when they're not.

npx vibemonetize doctor              # human-readable report
npx vibemonetize doctor --json       # machine-readable, for agents/CI

Flags

Exits 0 when nothing blocking was found (warnings are still allowed), 1 when any check failed — scriptable as a post-integration gate in CI or by a coding agent.

Env vars

Var Where What
VIBEMONETIZE_API_URL signup, app create, bundle create, grant, doctor Monetization API base URL, checked before .env.local. Falls back to https://api.vibemonetize.dev if nothing else is set.
VIBEMONETIZE_SECRET_KEY app create, bundle create, grant, doctor Developer secret key (sk_...), checked before .env.local. Never printed.
VIBEMONETIZE_INSTALL_CHANNEL any command Attribution tag on signup/init/app create events (assistant | cli | docs) — same as the --channel flag; ignored (with a warning, never a crash) if unset or invalid.

init/app create also write the client-side vars every VibeMonetize SDK reads — NEXT_PUBLIC_/VITE_-prefixed VIBEMONETIZE_APP_ID, _API_URL, _PUBLISHABLE_KEY, _TEST_PUBLISHABLE_KEY — plus, for Next.js, the unprefixed server-side VIBEMONETIZE_APP_ID, _API_URL, _SECRET_KEY, _TEST_SECRET_KEY that @vibemonetize/server reads by default. See the "init" section above for the full list with descriptions.

Options