> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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](./installation) for exact package commands.

## Scaffold a new project

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

```bash theme={null}
# 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](./quick-start) to protect your first endpoint
* [Installation](./installation) for manual setup
* [Core concepts](./core-concepts) for product, plan, and paywall behavior