CLI setup - SolvaPay Documentation

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:

Checks for package.json and offers to create one if missing
Detects your package manager (npm, yarn, or pnpm)
Opens your browser to sign in to SolvaPay Console
Writes SOLVAPAY_SECRET_KEY to .env
Ensures .env is listed in .gitignore
Installs @solvapay/server, @solvapay/core, and @solvapay/auth
Verifies your secret key with SolvaPay
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 the no-code MCP integration, 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

​Prerequisites

​Run setup

​What this command does

​Files the CLI creates or updates

​Add stack-specific packages

​Scaffold a new project

​Template types

​Re-run setup safely

​Scope

​Next steps