@paysmith/cli

The paysmith command-line tool. It inspects a project, activates an anonymous Paysmith sandbox funded with a deterministic $100.00 fake balance, and scaffolds a reversible $1 unlock demo so you can see content unlock only after a signed payment event is verified — no signup, no real money, 72-hour sandbox lifetime.

Install

pnpm add -g @paysmith/cli
# or
npm i -g @paysmith/cli

Or run it without installing:

npx @paysmith/cli init

The package exposes a single binary, paysmith; npx @paysmith/cli resolves to it directly.

Requires a Paysmith control plane (early access)

paysmith init needs a Paysmith control plane to talk to — it is what actually issues the sandbox, settles payments, and signs and delivers events. At v0.0.1:

• Point the CLI at one with --api-base <url>, or configure it however your team distributes that URL (e.g. an env var in your shell profile).
• A hosted, public sandbox endpoint is coming. Until it ships, the CLI is usable by teams that already have access to a Paysmith control plane — this is an early-access release.
• If you don't have a control-plane URL, ask whoever gave you this package for one; there is nothing else to configure once you have it.

Quick start

cd your-nextjs-app
npx @paysmith/cli init --api-base <your-control-plane-url>

paysmith init:

1. Inspects your project. Only Next.js App Router projects are supported today; anything else is rejected before anything on disk is touched.
2. Creates a private sandbox — anonymous, no signup, no email, no API key. It's funded with a deterministic $100.00 fake balance and expires in 72 hours.
3. Adds the $1 unlock demo — a demo page plus checkout, confirm, webhook, entitlement and receipt routes. It never overwrites an existing file with the same name: it picks a collision-free alternative and tells you.
4. Writes sandbox credentials to .env.local, records every generated file's path and sha256 hash in paysmith.generated.json, and adds .env.local and .paysmith/ to .gitignore — so the whole install is reversible with one later command.
5. Tells you the command to run and the URL to open.

Every run prints one of five progress states, in order:

Inspecting your app
Creating a private sandbox
Adding the $1 unlock demo
Running the payment flow
Ready — try the demo

...then a summary: sandbox id, fake balance, expiry, a masked sandbox token (the full value is only ever written to .env.local, never printed), the demo URL, and how many files were generated.

Commands

paysmith init

paysmith init [--api-base <url>] [--dir <path>]

• --api-base <url> — Paysmith control-plane base URL. Falls back to the PAYSMITH_API_BASE environment variable, then to http://127.0.0.1:4242 if neither is set.
• --dir <path> — target project directory. Defaults to ..

paysmith status

paysmith status [--api-base <url>] [--dir <path>]

Prints the sandbox id, live status, fake and available balance, expiry countdown, and the demo entitlement's current state — read live from the sandbox, not from local files. Without --api-base, it uses the API base recorded at init time.

paysmith remove

paysmith remove [--api-base <url>] [--dir <path>]

Reverses init:

• Deletes only the files listed in paysmith.generated.json whose sha256 hash still matches — anything you've edited since generation is preserved, with a manual cleanup guide printed for it (which .env.local lines to remove, the .gitignore block Paysmith added).
• Best-effort revokes the sandbox token; a failure to reach the control plane warns but never blocks local cleanup.
• Idempotent — running it again with nothing left to remove is a no-op.

How it fits

paysmith init is the on-ramp to all five primitives: it activates the sandbox, scaffolds a product and the route that turns it into a payment intent, wires up the signed event verification that is the only thing allowed to grant an entitlement, and exposes the resulting receipt — all reversible, before you write a line of integration code yourself.

License

MIT