Dodo CLI

Dodo CLI gestisce le risorse di Dodo Payments, risponde alle domande sul tuo account con un assistente AI integrato, crea sessioni di checkout e testa i webhook, tutto dal tuo terminale. Usa la sua TUI interattiva oppure esegui subcommand diretti dagli script.

Funzionalità

TUI interattiva: esegui dodo senza argomenti per aprire l’interfaccia interattiva, con tavolozza dei comandi, cronologia e notifiche in tempo reale.
Assistente AI integrato: poni domande o esegui azioni in linguaggio naturale con /ai. L’assistente esegue dodopayments-mcp localmente e non richiede configurazioni aggiuntive.
Credenziali crittografate: le chiavi API sono memorizzate in ~/.dodopayments/config.json, crittografate con AES-256-GCM e una chiave derivata dal tuo computer. Sul disco non vengono memorizzate credenziali in testo normale.
Aggiornamento automatico: CLI verifica la disponibilità di nuove versioni all’avvio e ti avvisa nella TUI. Per le installazioni tramite npm e Bun, esegui /update per aggiornare direttamente.
Strumenti per i webhook: inoltra i webhook in modalità test al tuo server locale oppure invia payload webhook simulati offline.
Scaffolding: aggiungi route di billing ai progetti Next.js, Express e Better Auth con dodo init.

Installazione

Su macOS o Linux, installa il binario dell’ultima release con lo script di installazione:

curl -fsSL https://dodopayments.com/install.sh | sh

Lo script verifica il binario confrontandolo con i checksum SHA-256 della release. Installa dodo nella prima directory scrivibile tra /usr/local/bin, ~/.local/bin e ~/bin oppure in ~/.local/bin se nessuna di queste è scrivibile. Per installare una release specifica, imposta la variabile d’ambiente DODO_VERSION sul relativo tag. Per scegliere la directory, imposta DODO_INSTALL_DIR.

Installazione con NPM o Bun

Se disponi di Node.js o Bun, installa globalmente il pacchetto dodopayments-cli. Le installazioni tramite package manager utilizzano l’ultima versione pubblicata:

npm install -g dodopayments-cli

bun install -g dodopayments-cli

I subcommand diretti come dodo login vengono eseguiti su Node.js 18 o versioni successive. Quando installi tramite un package manager, anche la TUI interattiva richiede Bun. I binari delle release non richiedono alcun runtime.

Installazione manuale (senza Node / Bun)

Per installare senza eseguire uno script remoto, scarica autonomamente il binario.

Download the Binary

Scarica il binario per la tua piattaforma dall’ultima GitHub Release.

Piattaforma	Binario
macOS (Apple Silicon)	`dodo-cli-darwin-arm64`
macOS (Intel)	`dodo-cli-darwin-x64`
Linux (x86_64)	`dodo-cli-linux-x64`
Linux (arm64)	`dodo-cli-linux-arm64`
Windows (x86_64)	`dodo-cli-windows-x64.exe`

Rename the Binary to dodo

mv ./dodo-cli-* ./dodo && chmod +x ./dodo

ren .\dodo-cli-windows-x64.exe .\dodo.exe

Move It to a Directory on Your PATH

Su Windows, spostare il file in C:\Windows\System32 richiede privilegi di amministratore.

sudo mv ./dodo /usr/local/bin/

move .\dodo.exe C:\Windows\System32\dodo.exe

(Optional) Verify the Download

Ogni release pubblica un file SHA256SUMS.txt. Scaricalo accanto al binario, quindi verifica il binario:

shasum -a 256 -c SHA256SUMS.txt

Autenticazione

Accedi con una chiave API prima di eseguire comandi che leggono o modificano il tuo account. Per accedere con un subcommand diretto, passa la chiave e la relativa modalità, test o live:

dodo login "$DODO_PAYMENTS_API_KEY" test

Oppure, dall’interno della TUI interattiva:

/login

Il flusso di accesso della TUI:

Apre nel browser la pagina Developer → API Keys della dashboard.
Ti chiede di incollare la chiave API.
Ti chiede di scegliere Test Mode o Live Mode.

Entrambi i comandi verificano la chiave con una richiesta all’API, quindi la memorizzano crittografata in ~/.dodopayments/config.json.

La chiave di crittografia viene derivata dal tuo computer, quindi le credenziali memorizzate funzionano solo su quel computer. Se esegui l’upgrade dalla versione v3.0.x, che memorizzava le chiavi nel portachiavi del sistema operativo, esegui nuovamente dodo login. Le chiavi nel precedente file in testo normale ~/.dodopayments/api-key vengono migrate automaticamente e il file viene eliminato.

Cambiare modalità e disconnettersi

Puoi mantenere contemporaneamente una chiave in modalità test e una chiave in modalità live. Per cambiare la modalità attiva nella TUI, esegui /switch. Per rimuovere le chiavi memorizzate:

dodo logout all

/logout

In modalità diretta, passa test, live o all. Nella TUI, /logout ti chiede di scegliere All accounts, Test Mode o Live Mode, quindi ti chiede di confermare.

Utilizzo

Puoi usare CLI in due modalità.

1. TUI interattiva (consigliata)

Esegui dodo senza argomenti per aprire l’interfaccia interattiva:

dodo

Digita / per aprire la tavolozza dei comandi. Il testo che non inizia con / viene inviato all’assistente AI.

Comando	Descrizione
`/help`	Mostra il riferimento dei comandi
`/update`	Verifica e installa un aggiornamento di CLI
`/login`	Autentica con una chiave API
`/logout`	Disconnette da uno o da tutti gli ambienti
`/switch`	Passa dalla modalità test alla modalità live e viceversa
`/clear`	Cancella la schermata della TUI
`/exit`	Esce dalla TUI (anche: digita `exit` oppure premi `Esc` due volte)

2. Subcommand diretti

Esegui un comando senza aprire la TUI:

dodo <category> <sub-command> [args...]

Ad esempio:

dodo payments list 1
dodo customers list 1
dodo wh trigger payment.success http://localhost:3000/webhook

Le tabelle di riferimento riportate di seguito elencano ogni comando nella modalità diretta. Nella TUI, sostituisci dodo con /, ad esempio /payments list 1. I comandi contrassegnati come TUI only sono procedure guidate interattive. In modalità diretta, stampano un messaggio che ti indica di aprire la TUI.

Assistente AI

Poni domande sul tuo account o esegui azioni in linguaggio naturale. L’assistente esegue dodopayments-mcp sul tuo computer, quindi non richiede configurazioni aggiuntive né un flusso OAuth. Chiama l’API di Dodo Payments dal tuo computer usando la chiave memorizzata e invia i tuoi prompt al modello linguistico.

Comando	Descrizione
`/ai <query>`	Poni una domanda all’assistente AI o impartiscigli un’istruzione
(qualsiasi testo che non inizi con una slash)	Viene inviato all’assistente AI per impostazione predefinita quando ti trovi nella TUI

In modalità diretta, esegui dodo ai seguito dalla tua domanda. Esempi nella TUI:

how much revenue did I make this week?
/ai create a new customer named Acme Inc.
/ai find my last failed payment

L’assistente usa la modalità attiva (modalità test o modalità live) e funziona solo con i dati di quella modalità.

Scaffolding del progetto

dodo init aggiunge route di billing di Dodo Payments a un progetto esistente. Scrive i file delle route, installa il pacchetto adapter @dodopayments/* corrispondente e aggiunge al file .env le variabili DODO_PAYMENTS_* mancanti con valori segnaposto. Ignora i file e le variabili già esistenti ed esegue il comando senza effettuare l’accesso.

dodo init <framework>

Scaffolding	Descrizione
`dodo init nextjs`	Crea le route di billing di Next.js App Router (checkout, Customer Portal e gestori webhook) usando `@dodopayments/nextjs`
`dodo init express`	Crea le route di billing per un server Express usando `@dodopayments/express`
`dodo init better-auth`	Crea la configurazione di un plugin Better-Auth usando `@dodopayments/better-auth`

Per lo scaffolding Better-Auth, puoi passare un elenco separato da virgole di plugin da generare: checkout, portal, usage e webhooks. Se non specifichi alcun elenco, vengono generati tutti e quattro.

# Scaffold every Better-Auth plugin (default)
dodo init better-auth

# Scaffold only specific plugins
dodo init better-auth checkout,portal

Se il tuo progetto dispone di una directory src/, lo scaffolder scrive i file al suo interno. Sceglie il comando di installazione dal file di lock del progetto (bun, pnpm o yarn) e usa npm quando non ne trova nessuno.

Riferimento dei comandi

Questi comandi richiedono una chiave API autenticata. I comandi di elenco accettano un numero di pagina facoltativo, che per impostazione predefinita è 1, e mostrano fino a 100 elementi per pagina.

Prodotti

Gestisci il catalogo dei prodotti.

Comando	Descrizione
`dodo products list <page>`	Elenca i prodotti
`dodo products create`	Apre la dashboard per creare un prodotto
`dodo products info <id>`	Visualizza i dettagli di un prodotto specifico

Pagamenti

Visualizza le transazioni di pagamento.

Comando	Descrizione
`dodo payments list <page>`	Elenca i pagamenti
`dodo payments info <id>`	Recupera le informazioni su un pagamento specifico

Clienti

Gestisci i tuoi clienti.

Comando	Descrizione
`dodo customers list <page>`	Elenca i clienti
`dodo customers create`	Crea un nuovo cliente (solo TUI)
`dodo customers update <id>`	Aggiorna un cliente esistente (solo TUI)
`dodo customers portal <id>`	Crea una sessione temporanea di Customer Portal per un cliente

Sconti

Gestisci i codici sconto.

Comando	Descrizione
`dodo discounts list <page>`	Elenca gli sconti
`dodo discounts create`	Crea un nuovo sconto basato su percentuale (solo TUI)
`dodo discounts delete <id>`	Rimuove uno sconto tramite ID (solo TUI)

Licenze

Visualizza le chiavi di licenza. Il comando si scrive licences.

Comando	Descrizione
`dodo licences list <page>`	Elenca le licenze

Addon

Gestisci gli addon dei prodotti.

Comando	Descrizione
`dodo addons list <page>`	Elenca gli addon
`dodo addons create`	Apre la dashboard per creare un addon
`dodo addons info <id>`	Visualizza i dettagli di un addon specifico

Rimborsi

Visualizza le informazioni sui rimborsi.

Comando	Descrizione
`dodo refunds list <page>`	Elenca i rimborsi
`dodo refunds info <id>`	Visualizza i dettagli di un rimborso specifico

Checkout

Crea sessioni di checkout ospitate.

Comando	Descrizione
`dodo checkout new`	Crea interattivamente una sessione di checkout ospitata e ottieni un link di pagamento (solo TUI)

Webhook

CLI dispone di due strumenti per webhook destinati allo sviluppo: un listener che inoltra i webhook in modalità test al tuo server locale e un trigger che invia payload webhook simulati a qualsiasi endpoint.

Comando	Descrizione
`dodo wh listen <url>`	Ascolta i webhook in tempo reale e inoltrali al server di sviluppo locale
`dodo wh trigger <event> <url>`	Invia un evento webhook simulato, anche senza aver effettuato l’accesso

In modalità diretta, gli argomenti sono obbligatori. Nella TUI, esegui /wh listen o /wh trigger senza argomenti per aprire una procedura guidata interattiva.

Ascoltare i webhook

Inoltra in tempo reale i webhook dal tuo account Dodo Payments al server di sviluppo locale.

dodo wh listen richiede una chiave API in Test Mode. Le chiavi in Live Mode non sono supportate dal flusso di ascolto.

dodo wh listen http://localhost:3000/webhook

Enter Your Local Endpoint URL

Passa l’URL locale che deve ricevere i webhook, ad esempio http://localhost:3000/webhook. Nella procedura guidata della TUI, CLI te lo chiede.

Automatic Setup

Se il tuo account non dispone di un endpoint webhook per il relay server di CLI, CLI ne crea uno. L’endpoint appare in Developer → Webhooks. CLI apre quindi una connessione WebSocket al relay per ricevere gli eventi in tempo reale.

Receive and Forward

Quando si attiva un evento webhook, ad esempio a seguito di un pagamento di test o di una modifica dell’abbonamento, CLI inoltra il payload e gli header al tuo endpoint locale come richiesta POST. Registra il tipo di evento e la risposta del tuo endpoint e invia la risposta al relay.

Il listener conserva gli header webhook originali (webhook-id, webhook-signature, webhook-timestamp) durante l’inoltro al tuo endpoint locale, così puoi testare la logica di verifica della firma.

Il relay e la CLI analizzano il corpo JSON e lo serializzano nuovamente prima di inoltrarlo. Se il corpo inoltrato differisce byte per byte dall’originale, ad esempio nella formattazione dei numeri, la verifica della firma non va a buon fine anche se le intestazioni sono intatte.

Attivare webhook di test

Invia un payload webhook simulato a qualsiasi endpoint, senza creare transazioni reali.

Gli eventi attivati non sono firmati: la richiesta non contiene l’header webhook-id, webhook-signature o webhook-timestamp. Durante i test, analizzali con il metodo non verificato (unsafeUnwrap in TypeScript, unsafe_unwrap in Python, UnsafeUnwrap in Go) invece di unwrap e torna a usare unwrap prima di andare in produzione.

dodo wh trigger payment.success http://localhost:3000/webhook

In modalità diretta, il payload utilizza ID e dettagli cliente segnaposto. La procedura guidata /wh trigger nella TUI ti accompagna attraverso questi passaggi:

Impostazione di un URL endpoint di destinazione.
Inserimento facoltativo di Business ID, Product ID, Metadata (un oggetto JSON), Customer email e Customer ID per il payload. I campi vuoti utilizzano valori segnaposto.
Selezione di un evento da inviare tramite un menu interattivo. Puoi inviare diversi eventi consecutivamente. Scegli exit per terminare.

dodo wh trigger non richiede l’accesso. Funziona come generatore locale e offline di payload webhook.

Eventi webhook supportati

dodo wh trigger può inviare payload simulati per 46 dei 48 tipi di evento forniti da Dodo Payments. Non supporta subscription.past_due o subscription.unpaused. Passa il nome dell’evento esattamente come riportato:

Categoria	Eventi
Subscription	`subscription.active`, `subscription.updated`, `subscription.on_hold`, `subscription.renewed`, `subscription.plan_changed`, `subscription.cancelled`, `subscription.failed`, `subscription.expired`, `subscription.paused`, `subscription.update_payment_method`
Payment	`payment.success`, `payment.failed`, `payment.processing`, `payment.cancelled`
Refund	`refund.success`, `refund.failed`
Dispute	`dispute.opened`, `dispute.expired`, `dispute.accepted`, `dispute.cancelled`, `dispute.challenged`, `dispute.won`, `dispute.lost`
License Key	`licence.created`
Payout	`payout.created`, `payout.in_progress`, `payout.on_hold`, `payout.failed`, `payout.success`
Credit	`credit.added`, `credit.deducted`, `credit.expired`, `credit.rolled_over`, `credit.rollover_forfeited`, `credit.overage_charged`, `credit.overage_reset`, `credit.manual_adjustment`, `credit.balance_low`
Abandoned Checkout	`abandoned_checkout.detected`, `abandoned_checkout.recovered`
Dunning	`dunning.started`, `dunning.recovered`
Entitlement Grant	`entitlement_grant.created`, `entitlement_grant.delivered`, `entitlement_grant.failed`, `entitlement_grant.revoked`

Tre nomi dei trigger differiscono dal nome dell’evento type nel payload che inviano: payment.success invia payment.succeeded, refund.success invia refund.succeeded e licence.created invia license_key.created.

Le strutture dei payload simulati seguono gli schemi corrispondenti nel riferimento API. Consulta Webhook Events per sapere cosa significa ogni evento e quando Dodo Payments lo genera in produzione.

payout.created viene generato mentre il payout riporta ancora uno stato not_initiated, quindi anche il payload simulato lo riflette. Consulta Payout Events per il ciclo di vita completo del payout.

Variabili d’ambiente

Questa variabile modifica il modo in cui dodo wh listen si connette:

Variabile	Descrizione
`DODO_WH_TEST_SERVER_URL`	Sostituisce il relay server webhook predefinito utilizzato da `dodo wh listen`. Imposta un nome host senza schema.

Aggiornamenti

CLI verifica la disponibilità di una versione più recente all’avvio e mostra una notifica nella barra di stato quando è disponibile. Per aggiornare un’installazione npm o Bun dalla TUI, esegui:

/update

/update non può aggiornare un binario di release. Per le installazioni tramite binario, incluse quelle effettuate con lo script di installazione, rimanda invece all’ultima release su GitHub. Per aggiornare dalla shell, esegui nuovamente il comando usato per l’installazione:

curl -fsSL https://dodopayments.com/install.sh | sh

npm install -g dodopayments-cli

bun install -g dodopayments-cli

Risorse

GitHub Repository

Codice sorgente e release.

npm Package

Il pacchetto dodopayments-cli nel registro npm.

Supporto

Discord: unisciti al server della community.
GitHub: apri una segnalazione nel repository.
Email: contatta support@dodopayments.com.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Funzionalità

Installazione

Installazione con NPM o Bun

Installazione manuale (senza Node / Bun)

Autenticazione

Cambiare modalità e disconnettersi

Utilizzo

1. TUI interattiva (consigliata)

2. Subcommand diretti

Assistente AI

Scaffolding del progetto

Riferimento dei comandi

Prodotti

Pagamenti

Clienti

Sconti

Licenze

Addon

Rimborsi

Checkout

Webhook

Ascoltare i webhook

Attivare webhook di test

Eventi webhook supportati

Variabili d’ambiente

Aggiornamenti

Risorse

GitHub Repository

npm Package

Supporto

​Funzionalità

​Installazione

​Installazione con NPM o Bun

​Installazione manuale (senza Node / Bun)

​Autenticazione

​Cambiare modalità e disconnettersi

​Utilizzo

​1. TUI interattiva (consigliata)

​2. Subcommand diretti

​Assistente AI

​Scaffolding del progetto

​Riferimento dei comandi

​Prodotti

​Pagamenti

​Clienti

​Sconti

​Licenze

​Addon

​Rimborsi

​Checkout

​Webhook

​Ascoltare i webhook

​Attivare webhook di test

​Eventi webhook supportati

​Variabili d’ambiente

​Aggiornamenti

​Risorse

GitHub Repository

npm Package

​Supporto

Funzionalità

Installazione

Installazione con NPM o Bun

Installazione manuale (senza Node / Bun)

Autenticazione

Cambiare modalità e disconnettersi

Utilizzo

1. TUI interattiva (consigliata)

2. Subcommand diretti

Assistente AI

Scaffolding del progetto

Riferimento dei comandi

Prodotti

Pagamenti

Clienti

Sconti

Licenze

Addon

Rimborsi

Checkout

Webhook

Ascoltare i webhook

Attivare webhook di test

Eventi webhook supportati

Variabili d’ambiente

Aggiornamenti

Risorse

Supporto