# Guida rapida con npx

> Un comando configura Perly Pay nel tuo progetto: la route di checkout, la route del webhook con verifica della firma, un pulsante Pay e la tua chiave di test.

`npx perly-pay init` legge il tuo progetto, scrive codice per il suo framework e ti lascia a un clic da un pagamento di test. Configura solo la **modalità test**; la modalità live si attiva nella dashboard.

## Eseguilo

```bash
npx perly-pay init
```

Rileva il framework e il gestore di pacchetti, apre Dashboard → Developers e chiede una chiave di test (`sk_test_…`). Rifiuta una chiave live.

## Cosa scrive

| Framework | Come lo rileva | File |
| --- | --- | --- |
| Next.js (App Router) | `next` | `lib/perly-pay.ts`, `app/api/perly-pay/checkout/route.ts`, `app/api/perly-pay/webhook/route.ts`, `components/PayButton.tsx`, `app/perly-pay/page.tsx` |
| Express | `express` | `lib/perly-pay.js`, `routes/perly-pay.js` |
| Hono | `hono` | `lib/perly-pay.ts`, `routes/perly-pay.ts` |
| Laravel | `artisan`, `laravel/framework` | `app/Http/Controllers/PerlyPayController.php`, `routes/perly-pay.php`, `config/perly-pay.php`, `resources/views/perly-pay/button.blade.php` |
| Node.js | qualsiasi altro `package.json` | `lib/perly-pay.js`, `perly-pay.js` (`node:http`) |

TypeScript o JavaScript, moduli ES o CommonJS, come il tuo progetto, e in `src/` se il tuo codice è lì. npm, pnpm, yarn, bun e Composer.

- **Checkout.** Il pulsante invia un form a `/perly-pay/checkout` (`/api/perly-pay/checkout` in Next.js). Apre una fattura e porta l’acquirente a pagarla.
- **Webhook.** `/perly-pay/webhook` verifica `Perly-Signature` sul body grezzo. Con `invoice.fulfilled` chiama `grantAccess()`, l’unico TODO che scrivi tu.
- **Piani.** Vendite una tantum e pacchetti di crediti, in `PLANS` in cima al modulo principale. Il piano, i suoi crediti e il tuo id utente viaggiano nei metadati della fattura e tornano nel webhook.
- **Chiavi.** `PERLY_PAY_SECRET_KEY` e `PERLY_PAY_WEBHOOK_SECRET` in `.env.local` (Next.js) o `.env`, e il file in `.gitignore`. Se git traccia già quel file, init non ci scrive la chiave e ti dice come smettere di tracciarlo.

> **Nota:** init non sostituisce mai un file o un valore già presente. `--force` sì.

## Collega il webhook

Perly Pay deve poter raggiungere l’indirizzo del webhook. Aggiungilo in Dashboard → Developers → Webhooks per `invoice.fulfilled` e incolla il suo segreto `whsec_…` in `PERLY_PAY_WEBHOOK_SECRET`. Oppure lascia che init faccia entrambe le cose:

```bash
npx perly-pay init --webhook-url https://your-app.example/perly-pay/webhook
```

Su un portatile, un tunnel ti dà un indirizzo pubblico: `cloudflared tunnel --url http://localhost:3000`. Altro in [Webhook](https://pay.perly.io/docs/webhooks.md).

## Un pagamento in modalità test

1. **Avvia la tua app** — Express e Node leggono `.env` con `node --env-file=.env` o dotenv.
2. **Apri /perly-pay** — Tocca **Pay with crypto**. Sei sul checkout.
3. **Simulate payment** — La fattura diventa pagata e poi consegnata. Vedi [Modalità test](https://pay.perly.io/docs/test-mode.md).
4. **Guarda grantAccess in azione** — Il tuo webhook riceve `invoice.fulfilled`. Ora scrivi cosa concede.

## Con un assistente AI

`--yes` non chiede nulla, quindi Claude Code, Cursor o Codex possono eseguirlo per te. Dagli la chiave e cosa vendi:

```bash
npx perly-pay init --yes --key sk_test_… --product "Logo review" --amount 4900
```

`--json` stampa un risultato che l’assistente può leggere.

## Opzioni

| Flag | Cosa fa |
| --- | --- |
| `--yes`, `-y` | Nessuna domanda. Per assistenti AI e script. |
| `--framework <name>` | `next`, `express`, `hono`, `laravel` o `node`, se non l’ha indovinato. |
| `--key <sk_test_…>` | La tua chiave di test. Di default: `PERLY_PAY_SECRET_KEY`, oppure la chiede. |
| `--webhook-url <url>` | Registra l’indirizzo per `invoice.fulfilled` e salva il suo segreto. |
| `--product <name>`, `--amount <cents>`, `--currency <code>` | Cosa vendi, in USD o EUR. `--amount 4900` è $49.00. |
| `--install` | Installa anche l’SDK. Altrimenti stampa il comando. |
| `--force` | Sostituisce i file e i valori già presenti. |
| `--plugin`, `--mcp` | Stampa come aggiungere il plugin di Claude Code e il server `perly-pay-mcp`. |
| `--dry-run` | Dice cosa farebbe, senza scrivere nulla. |
| `--json` | Stampa il risultato come JSON. |
| `--api <origin>`, `--dir <path>` | Un altro Perly Pay (locale), un’altra cartella. |

## Modalità live

- Collega le chiavi **live** del tuo wallet in Dashboard → Wallets.
- Crea una chiave live (`sk_live_…`) e un webhook live.
- Impostali dove gira la tua app. Il codice resta uguale. Il resto dell’API è negli [SDK](https://pay.perly.io/docs/sdks.md).