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 init — add SolvaPay to an existing project
• npm create solvapay — scaffold a new project from a template

Prerequisites

• Node.js version 18.17 or higher
• A project directory where you want to add SolvaPay (for solvapay init)

Run setup

From your project root:

npx solvapay init

What this command does

When you run npx solvapay 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 my-mcp-app -- --type mcp

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

# Next.js + Auth0 starter with SolvaPay customer linkage
npm create solvapay 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 -- --list-types to see available templates.

Re-run setup safely

You can run npx solvapay 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.

Next steps

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