CLI setup

Set up SolvaPay SDK in an existing project, or scaffold a new one from a template.

Two CLIs cover the two starting points:

• npx solvapay@latest init — add SolvaPay to an existing project
• npm create solvapay@latest — scaffold a new project from a template (npx create-solvapay@latest is equivalent)

​

Prerequisites

• Node.js 22 or later (the CLI installs @solvapay/server, which requires it)
• A project directory where you want to add SolvaPay (for solvapay init)

​

Run setup

From your project root:

npx solvapay@latest init

​

What this command does

When you run npx solvapay@latest init, the CLI:

1. Checks for package.json and offers to create one if missing
2. Detects your package manager (npm, yarn, or pnpm)
3. Opens your browser to sign in to SolvaPay Console
4. Writes SOLVAPAY_SECRET_KEY to .env
5. Ensures .env is listed in .gitignore
6. Installs @solvapay/server, @solvapay/core, and @solvapay/auth
7. Verifies your secret key with SolvaPay
8. Prints a quick start snippet

​

Files the CLI creates or updates

File	What changes
package.json	Created if missing (after confirmation)
.env	Adds or updates SOLVAPAY_SECRET_KEY
.gitignore	Adds .env if needed
node_modules and lockfile	Installs base SolvaPay SDK packages

​

Add stack-specific packages

solvapay init installs base server packages. Add framework packages based on your stack:

• Next.js: @solvapay/next and usually @solvapay/react
• React: @solvapay/react (and @solvapay/react-supabase if using Supabase)
• MCP Server: @solvapay/server is already installed by init

Use Installation for exact package commands.

​

Scaffold a new project

To start from scratch, use the create-solvapay scaffolder instead of init:

# Paid MCP server (Cloudflare Worker + embedded checkout widget)
npm create solvapay@latest my-mcp-app -- --type mcp

# Generate MCP tools from an OpenAPI spec
npm create solvapay@latest my-api-mcp -- --type mcp --openapi ./openapi.yaml

# Next.js + Auth0 starter with SolvaPay customer linkage
npm create solvapay@latest my-app -- --type next-auth0

​

Template types

--type	What you get
mcp	A paid MCP server on Cloudflare Workers: @solvapay/mcp server factory, OAuth bridge, and an embedded checkout widget built with @solvapay/react/mcp. With --openapi <url|path>, tools are generated from your API spec; with --no-openapi you get a placeholder paid tool
next-auth0	A Next.js App Router starter wired for Auth0: @auth0/nextjs-auth0 session handling, createAuth0AuthMiddleware from @solvapay/next/middleware, and the externalRef customer linkage set up for you. --auth auth0 is a shortcut for this type

Useful flags: --product <ref> to pre-select a product, -y / --non-interactive for CI, --skip-install, and --skip-init (the scaffolder runs solvapay init at the end unless you skip it). Run npm create solvapay@latest -- --list-types to see available templates.

​

Re-run setup safely

You can run npx solvapay@latest init again at any time.

If SOLVAPAY_SECRET_KEY already exists, the CLI asks whether to overwrite it:

• Choose y to replace it with a new key
• Choose n to keep your current key

​

Scope

These commands are the recommended setup paths for SDK integration.

If you are using Managed MCP, you do not need either CLI flow.

​

Stale scaffolder cache

@latest is required, but npx can still reuse a cached create-solvapay tarball. Every run prints create-solvapay vX.Y.Z — check that banner against the published version. If it lags:

npx clear-npx-cache
npm create solvapay@latest my-mcp-app -- --type mcp

​

Next steps

• Quick start to protect your first endpoint
• Installation for manual setup
• Core concepts for product, plan, and paywall behavior