Billing SDK CLI Reference

Copy Page

The Billing SDK CLI is a powerful command-line tool that helps you initialize new billing projects, add components, and manage your billing infrastructure with ease.

Installation

The CLI is published as an npm package and can be used with npx without installation:

npx @billingsdk/cli --help

For frequent use, you can install it globally:

npm install -g @billingsdk/cli
@billingsdk/cli --help

Commands

@billingsdk/cli init

Initialize a new billing project with complete setup including framework configuration, payment provider integration, and essential dependencies.

Usage

npx @billingsdk/cli init

What it does

1. Framework Selection: Choose your preferred framework (Next.js or Express.js)
2. Provider Selection: Select your payment provider (currently Dodo Payments)
3. Template Installation: Downloads and installs framework-specific templates
4. Dependency Management: Automatically installs required dependencies
5. File Generation: Creates necessary configuration files and boilerplate code

Interactive Setup

The command launches an interactive setup process:

npx @billingsdk/cli init

You'll be prompted to select:

• Framework: Next.js (with App Router) or Express.js (Node.js web framework)
• Payment Provider: Dodo Payments

Generated Files

After running init, you'll get:

your-project/
├── app/api/
│   ├── (dodopayments)/
│   │   ├── checkout/route.ts
│   │   ├── customer/route.ts
│   │   ├── customer/payments/route.ts
│   │   ├── customer/subscriptions/route.ts
│   │   ├── product/route.ts
│   │   ├── products/route.ts
│   │   └── webhook/route.ts
├── hooks/
│   └── useBilling.ts
├── lib/
│   └── dodopayments.ts
└── .env.example

your-project/
├── src/
│   ├── lib/
│   │   └── dodopayments.ts
│   └── routes/
│       └── dodopayments/
│           ├── route.ts
│           ├── checkout.ts
│           ├── customer.ts
│           ├── payments.ts
│           ├── products.ts
│           ├── subscriptions.ts
│           └── webhook.ts
└── .env.example

API Routes Included

The init command sets up comprehensive API routes for:

• Checkout: Payment processing and order creation
• Customer Management: Customer data and subscription handling
• Product Management: Product catalog and pricing
• Webhook Handling: Payment provider webhook integration

Dependencies Installed

{
  "dependencies": {
    "dodopayments": "latest",
    "standardwebhooks": "latest",
    "zod": "latest"
  }
}

{
  "dependencies": {
    "dodopayments": "latest",
    "standardwebhooks": "latest",
    "zod": "latest",
    "express": "latest",
    "@types/express": "latest"
  }
}

Express.js Setup Instructions

Basic Express.js Integration

After running @billingsdk/cli init and selecting Express.js, you'll need to integrate the generated routes into your Express application:

// app.js or server.js
const express = require('express');
const { dodopaymentsRouter } = require('./src/routes/dodopayments/route');

const app = express();

// Middleware
app.use(express.json());

// Mount DodoPayments routes
app.use('/api/dodopayments', dodopaymentsRouter);

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Environment Configuration

Create a .env file in your project root:

# DodoPayments Configuration
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_ENVIRONMENT=test_mode
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_key_here

# Server Configuration
PORT=3000
NODE_ENV=development

Available API Endpoints

The Express.js template provides these endpoints:

• POST /api/dodopayments/checkout - Create checkout sessions
• GET /api/dodopayments/customer - Retrieve customer data
• POST /api/dodopayments/customer - Create new customers
• PUT /api/dodopayments/customer - Update customer information
• GET /api/dodopayments/customer/subscriptions - Get customer subscriptions
• GET /api/dodopayments/customer/payments - Get customer payment history
• GET /api/dodopayments/products - List all products
• GET /api/dodopayments/product - Get specific product details
• GET /api/dodopayments/subscriptions - Retrieve subscription details
• GET /api/dodopayments/payments - Get payment information
• POST /api/dodopayments/webhook - Handle DodoPayments webhooks

TypeScript Support

The template includes full TypeScript support. To use with TypeScript:

npm install -D typescript @types/node ts-node nodemon

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Update your package.json scripts:

{
  "scripts": {
    "dev": "nodemon --exec ts-node src/app.ts",
    "build": "tsc",
    "start": "node dist/app.js"
  }
}

@billingsdk/cli add

Add individual billing components to your existing project using the shadcn/ui registry system.

Usage

npx @billingsdk/cli add <component-name>

Available Components

See the components page for a list of available components.

Examples

# Add a pricing table
npx @billingsdk/cli add pricing-table-one

# Add subscription management
npx @billingsdk/cli add subscription-management

# Add usage monitoring
npx @billingsdk/cli add usage-meter-circle

What happens

1. Downloads the component configuration from the registry
2. Installs the component files in your components/billingsdk/ directory
3. Updates your project configuration if needed
4. Installs any additional dependencies

Supported Frameworks

Next.js (App Router)

• ✅ Status: Fully supported
• 📁 Structure: App Router with API routes
• 🔧 Features: Server components, server actions, middleware support

Express.js

• ✅ Status: Fully supported
• 📁 Structure: Modular route-based architecture
• 🔧 Features: RESTful API routes, middleware support, TypeScript integration

Coming Soon

• 🚧 Fastify: High-performance backend framework
• 🚧 Additional React Frameworks: Vite, Remix support

Supported Payment Providers

Dodo Payments

• ✅ Status: Fully supported
• 🔧 Features: Payment processing, subscriptions, webhooks
• 📚 Integration: Complete API route templates included

Coming Soon

• 🚧 Stripe: Industry-standard payment processing
• 🚧 Additional Providers: Based on community demand

Configuration

Environment Variables

After running @billingsdk/cli init, configure these environment variables:

# Dodo Payments Configuration
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test"or"live"

# Next.js Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

Customizing Templates

The CLI uses templates from the public registry. You can:

• Modify generated files after installation
• Create custom templates for your organization
• Extend existing components with additional features

Troubleshooting

Common Issues

Command not found

# Make sure you're using npx
npx @billingsdk/cli --help

Permission errors

# On Unix systems, you might need to adjust permissions
chmod +x node_modules/.bin/@billingsdk/cli

Network issues

# Check your internet connection
# The CLI downloads templates from @billingsdk/cli.com

Getting Help

# Show all available commands
npx @billingsdk/cli --help

# Get help for a specific command
npx @billingsdk/cli init --help
npx @billingsdk/cli add --help

Development

Building the CLI

cd packages/cli
npm run build

Development Mode

cd packages/cli
npm run dev

Contributing

The CLI is open source and welcomes contributions. See our contribution guide for details.