@ducksauce/cli

Command-line interface tools for managing Ducksauce projects, including project initialization, license activation, and component scaffolding.

🚀 Quick Start

Installation

npm install -g @ducksauce/cli
# or
yarn global add @ducksauce/cli
# or
pnpm add -g @ducksauce/cli

Usage

# Initialize a new project
ducksauce init

# Activate license
ducksauce license activate

# Scaffold components
ducksauce scaffold component

🛠️ Commands

init

Initialize a new Ducksauce project with Payload CMS and Next.js.

ducksauce init [project-name]

Options

• --template <template> - Choose project template (default: basic)
• --package-manager <manager> - Package manager (npm, yarn, pnpm)
• --typescript - Use TypeScript (default: true)
• --tailwind - Include Tailwind CSS (default: true)
• --git - Initialize git repository (default: true)

Examples

# Basic initialization
ducksauce init my-project

# With specific template
ducksauce init my-project --template blog

# With custom package manager
ducksauce init my-project --package-manager pnpm

# Without TypeScript
ducksauce init my-project --typescript false

Templates

• basic - Minimal Payload CMS + Next.js setup
• blog - Blog-focused template with posts and categories
• ecommerce - E-commerce template with products and orders
• saas - SaaS template with user management and billing

license

Manage Ducksauce licenses and entitlements.

ducksauce license <command>

Commands

activate

Activate a license key.

ducksauce license activate <license-key>

status

Check license status and entitlements.

ducksauce license status

deactivate

Deactivate current license.

ducksauce license deactivate

Examples

# Activate license
ducksauce license activate ds_1234567890abcdef

# Check status
ducksauce license status

# Deactivate
ducksauce license deactivate

scaffold

Generate files and components for your project.

ducksauce scaffold <template> [name]

Templates

component

Generate a React component.

ducksauce scaffold component Button

Options:

• --path <path> - Output path (default: src/components)
• --typescript - Use TypeScript (default: true)
• --styled - Include styled-components
• --test - Include test file

page

Generate a Next.js page.

ducksauce scaffold page about

Options:

• --path <path> - Output path (default: src/app)
• --typescript - Use TypeScript (default: true)
• --layout - Include layout file
• --api - Include API route

collection

Generate a Payload CMS collection.

ducksauce scaffold collection Product

Options:

• --path <path> - Output path (default: src/collections)
• --fields - Include common fields
• --hooks - Include collection hooks
• --access - Include access control

block

Generate a Payload CMS block.

ducksauce scaffold block Hero

Options:

• --path <path> - Output path (default: src/blocks)
• --admin - Include admin component
• --frontend - Include frontend component

Examples

# Generate component
ducksauce scaffold component Button --typescript --test

# Generate page
ducksauce scaffold page about --layout --api

# Generate collection
ducksauce scaffold collection Product --fields --hooks

# Generate block
ducksauce scaffold block Hero --admin --frontend

🛠️ Development

Prerequisites

• Node.js 18.20.2 or >=20.9.0
• pnpm 10.13.1+

Setup

# Install dependencies
pnpm install

# Start development mode
pnpm dev

# Build for production
pnpm build

# Run linting
pnpm lint

# Clean build artifacts
pnpm clean

Project Structure

packages/cli/
├── src/
│   ├── cli.ts              # Main CLI entry point
│   ├── index.ts            # Main exports
│   ├── commands/           # Command implementations
│   │   ├── init.ts
│   │   ├── license.ts
│   │   └── scaffold.ts
│   └── utils/              # Utility functions
│       ├── license.ts
│       └── workspace.ts
├── package.json
├── tsconfig.json
└── README.md

Adding New Commands

1. Create command file in src/commands/
2. Export from src/index.ts
3. Add to CLI in src/cli.ts
4. Update this README

Example Command

// src/commands/example.ts
import { Command } from "commander";
import chalk from "chalk";
import ora from "ora";

export const exampleCommand = new Command("example")
  .description("Example command description")
  .argument("[name]", "Name argument")
  .option("-f, --flag", "Example flag")
  .action(async (name, options) => {
    const spinner = ora("Running example command...").start();

    try {
      // Command logic here
      console.log(chalk.green(`Hello ${name || "World"}!`));
      spinner.succeed("Command completed successfully");
    } catch (error) {
      spinner.fail("Command failed");
      console.error(chalk.red(error.message));
      process.exit(1);
    }
  });

📦 Building

Development Build

pnpm dev

This starts tsup in watch mode, rebuilding on file changes.

Production Build

pnpm build

This creates:

• dist/cli.js - CLI executable
• dist/index.js - Main exports
• dist/index.d.ts - TypeScript declarations

Build Configuration

The package uses tsup for building:

{
  "build": "tsup src/cli.ts src/index.ts --dts --format esm"
}

🧪 Testing

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests with coverage
pnpm test --coverage

📦 Publishing

Versioning

This package uses Changesets for versioning:

1. Create a changeset: pnpm changeset
2. Version the package: pnpm release
3. Publish: pnpm release (includes publishing)

Manual Publishing

# Build the package
pnpm build

# Publish to npm
pnpm publish

Package Configuration

{
  "name": "@ducksauce/cli",
  "version": "0.0.0",
  "type": "module",
  "bin": {
    "ducksauce": "dist/cli.js"
  },
  "main": "dist/index.js",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "sideEffects": false,
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}

🔗 Dependencies

Dependencies

• commander - CLI framework
• inquirer - Interactive prompts
• chalk - Terminal colors
• ora - Terminal spinners
• fs-extra - File system utilities
• glob - File pattern matching

Dev Dependencies

• @types/node - Node.js TypeScript types
• @types/inquirer - Inquirer TypeScript types
• @types/fs-extra - fs-extra TypeScript types
• @types/glob - glob TypeScript types
• eslint - Code linting
• tsup - TypeScript bundler
• typescript - TypeScript compiler

📚 API Reference

CLI Commands

init

Initialize a new Ducksauce project.

ducksauce init [project-name] [options]

license

Manage licenses and entitlements.

ducksauce license activate <key>
ducksauce license status
ducksauce license deactivate

scaffold

Generate project files and components.

ducksauce scaffold <template> [name] [options]

Utility Functions

checkWorkspace

Check if current directory is a Ducksauce workspace.

import { checkWorkspace } from "@ducksauce/cli";

const isWorkspace = await checkWorkspace();

validateLicense

Validate a license key.

import { validateLicense } from "@ducksauce/cli";

const isValid = await validateLicense(licenseKey);

🔐 License Management

The CLI includes license management features for the Ducksauce platform.

License Storage

Licenses are stored locally in:

• ~/.ducksauce/licenses.json (global)
• .ducksauce/license.json (project-specific)

License Validation

Licenses are validated against the Ducksauce license server and include:

• License Key - Unique identifier
• Features - Enabled features (blog, analytics, etc.)
• Expiry Date - License expiration
• User ID - Associated user account

Feature Entitlements

Licenses control access to features:

• Basic - Core CMS functionality
• Pro - Advanced features, analytics, custom domains
• Enterprise - White-label, priority support

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Create a changeset
6. Submit a pull request

📄 License

This package is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: This README
• Issues: Create an issue in the repository
• Discussions: Use GitHub Discussions for questions

Built with ❤️ using Commander.js and Inquirer.js.