Pushduck CLI

Zero-configuration setup for Next.js file uploads. Get production-ready S3 uploads working in under 2 minutes.

Quick Start

1npx @pushduck/cli@latest init

That's it! The CLI will guide you through setting up:

• ✅ Provider configuration (AWS S3, Cloudflare R2, etc.)
• ✅ API route generation with TypeScript
• ✅ Example upload components
• ✅ Environment variable setup
• ✅ Bucket creation (optional)

Commands

init - Initialize Your Project

1npx @pushduck/cli@latest init [options]

Options:

• --provider <type> - Skip provider selection (aws|cloudflare-r2|digitalocean|minio|gcs)
• --skip-examples - Don't generate example components
• --skip-bucket - Don't create S3 bucket automatically
• --api-path <path> - Custom API route path (default: /api/upload)
• --dry-run - Show what would be created without creating
• --verbose - Show detailed output

Examples:

1# Interactive setup with all prompts
2npx @pushduck/cli@latest init
3
4# Use AWS S3 directly, skip examples
5npx @pushduck/cli@latest init --provider aws --skip-examples
6
7# Custom API path  
8npx @pushduck/cli@latest init --api-path /api/files
9
10# Preview without creating files
11npx @pushduck/cli@latest init --dry-run

add - Add Upload Routes

1npx @pushduck/cli@latest add

Add new upload routes to your existing configuration. Interactive route builder helps you:

• Define file types and validation
• Set up middleware and authentication
• Configure upload destinations
• Generate TypeScript types

test - Validate Setup

1npx @pushduck/cli@latest test [--verbose]

Validates your current configuration:

• ✅ Environment variables
• ✅ S3 bucket connectivity
• ✅ CORS configuration
• ✅ API route functionality
• ✅ TypeScript compilation

What Gets Created

The CLI generates a complete, production-ready setup:

your-project/
├── app/api/upload/route.ts        # Type-safe upload API
├── app/upload/page.tsx            # Demo upload page  
├── components/ui/
│   ├── upload-button.tsx          # Simple upload button
│   ├── upload-dropzone.tsx        # Drag & drop component
│   └── file-preview.tsx           # File preview component
├── lib/upload-client.ts           # Type-safe upload client
├── .env.local                     # Environment variables
└── .env.example                   # Environment template

Generated API Route

1// app/api/upload/route.ts
2import { createUploadRouter, uploadSchema } from 'pushduck/server'
3
4export const router = createUploadRouter({
5  imageUpload: uploadSchema({
6    image: {
7      maxSize: "5MB",
8      maxCount: 1,
9      formats: ["jpeg", "png", "webp"]
10    }
11  }).middleware(async ({ req }) => {
12    // Add your authentication logic
13    const userId = await getUserId(req)
14    return { userId, folder: `uploads/${userId}` }
15  }),
16
17  documentUpload: uploadSchema({
18    file: {
19      maxSize: "10MB", 
20      maxCount: 5,
21      allowedTypes: ["application/pdf", "text/plain"]
22    }
23  }).middleware(async ({ req }) => {
24    const userId = await getUserId(req)
25    return { userId, folder: `documents/${userId}` }
26  })
27})
28
29export type AppRouter = typeof router
30export const { GET, POST } = router

Generated Upload Client

1// lib/upload-client.ts
2import { createUploadClient } from 'pushduck/client'
3import type { AppRouter } from '@/app/api/upload/route'
4
5export const upload = createUploadClient<AppRouter>({
6  endpoint: '/api/upload'
7})
8
9// Property-based access with full type safety
10export const { imageUpload, documentUpload } = upload

Generated Components

1// components/ui/upload-button.tsx
2'use client'
3
4import { upload } from '@/lib/upload-client'
5
6export function UploadButton() {
7  const { uploadFiles, uploadedFiles, isUploading, progress } = upload.imageUpload()
8
9  return (
10    <div>
11      <input
12        type="file"
13        onChange={(e) => uploadFiles(e.target.files)}
14        disabled={isUploading}
15      />
16      {isUploading && <div>Progress: {progress}%</div>}
17      {uploadedFiles.map(file => (
18        <img key={file.key} src={file.url} alt="Uploaded" />
19      ))}
20    </div>
21  )
22}

Provider Support

The CLI supports all major S3-compatible providers:

• AWS S3 - The original and most feature-complete
• Cloudflare R2 - Global edge network, S3-compatible
• DigitalOcean Spaces - Simple and affordable
• Google Cloud Storage - Enterprise-grade with global reach
• MinIO - Self-hosted, open source S3 alternative

Provider-Specific Setup

Each provider has tailored setup:

1# AWS S3 with automatic IAM policy creation
2npx @pushduck/cli@latest init --provider aws
3
4# Cloudflare R2 with edge optimization
5npx @pushduck/cli@latest init --provider cloudflare-r2
6
7# DigitalOcean Spaces with CDN setup
8npx @pushduck/cli@latest init --provider digitalocean
9
10# MinIO for local development
11npx @pushduck/cli@latest init --provider minio

Interactive Setup Flow

The CLI provides a guided setup experience:

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   🚀 Welcome to Pushduck                       │
│                                                             │
│   Let's get your file uploads working in 2 minutes!        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🔍 Detecting your project...
  ✓ Next.js App Router detected
  ✓ TypeScript configuration found
  ✓ No existing upload configuration

? Which cloud storage provider would you like to use?
❯ AWS S3 (recommended)
  Cloudflare R2 (S3-compatible, global edge)
  DigitalOcean Spaces (simple, affordable)

🔧 Setting up AWS S3...
🔍 Checking for existing credentials...
  ✓ Found AWS_ACCESS_KEY_ID
  ✓ Found AWS_SECRET_ACCESS_KEY
  ✓ Found AWS_REGION

? Enter your S3 bucket name: my-app-uploads
? Create bucket automatically? Yes

🛠️ Generating files...
✨ Created files:
  ├── app/api/upload/route.ts
  ├── app/upload/page.tsx
  ├── components/ui/upload-button.tsx
  ├── lib/upload-client.ts
  └── .env.example

📦 Installing dependencies...
  ✓ pushduck
  ✓ @aws-sdk/client-s3

🎉 Setup complete! Your uploads are ready.

Troubleshooting

CLI Not Found

1# If you get "command not found"
2npm install -g pushduck
3
4# Or use npx for one-time usage  
5npx @pushduck/cli@latest@latest init

Permission Errors

1# If you get permission errors during setup
2sudo npx @pushduck/cli@latest init
3
4# Or fix npm permissions
5npm config set prefix ~/.npm-global
6export PATH=~/.npm-global/bin:$PATH

Bucket Creation Failed

1# Test your credentials first
2npx @pushduck/cli@latest test
3
4# Skip automatic bucket creation
5npx @pushduck/cli@latest init --skip-bucket
6
7# Create bucket manually, then run:
8npx @pushduck/cli@latest test

Advanced Usage

Non-Interactive Mode

1# For CI/CD environments
2npx @pushduck/cli@latest init \
3  --provider aws \
4  --skip-examples \
5  --api-path /api/upload \
6  --no-interactive

Custom Templates

1# Use enterprise template with security features
2npx @pushduck/cli@latest init --template enterprise
3
4# Use minimal template for existing projects
5npx @pushduck/cli@latest init --template minimal

Monorepo Support

1# For monorepos, specify the Next.js app directory
2cd apps/web
3npx @pushduck/cli@latest init
4
5# Or use the --cwd flag
6npx @pushduck/cli@latest init --cwd apps/web

Contributing

The CLI is part of the pushduck monorepo.

1# Clone the repository
2git clone https://github.com/your-org/pushduck.git
3
4# Install dependencies
5pnpm install
6
7# Development
8cd packages/cli
9pnpm dev
10
11# Build
12pnpm build
13
14# Test locally
15npm link
16pushduck init

License

MIT © Abhay Ramesh