@swoft/cli v1.0.0

@swoft/cli

🚀 Swiss Army knife CLI for building Swoft applications with clean architecture

The official Swoft CLI tool that helps you create production-ready applications using clean architecture, domain-driven design, and modern development practices.

Quick Start

Create your first Swoft application in seconds:

# Create a new backend API
npx @swoft/cli create:app my-api --type backend --features mongodb,auth

# Navigate to your app
cd my-api

# Install dependencies
pnpm install

# Start developing
pnpm dev

That's it! Your new application is ready with:

• ✅ Clean architecture structure
• ✅ MongoDB integration
• ✅ JWT authentication
• ✅ TypeScript configuration
• ✅ Development environment
• ✅ Production build setup

Installation

Global Installation (Recommended)

npm install -g @swoft/cli

Then use anywhere:

swoft create:app my-project
swoft create:domain user-management

One-time Usage

npx @swoft/cli create:app my-project

Commands

Create Application

Create a complete new application workspace:

swoft create:app <name> [options]

Options:

• --type <type> - Application type (backend, frontend, desktop, cli, microservice)
• --description <desc> - Application description
• --features <features> - Comma-separated features (mongodb, auth, ai, realtime, storage, jobs, docs)
• --interactive - Enable interactive prompts (default: auto-detect)

Examples:

# Backend API with MongoDB and auth
swoft create:app my-api --type backend --features mongodb,auth

# Frontend web app
swoft create:app my-web --type frontend

# Desktop app with AI features
swoft create:app my-desktop --type desktop --features ai,storage

# CLI tool
swoft create:app my-tool --type cli

Create Domain Package

Create a domain package with clean architecture:

swoft create:domain <name> [options]

Options:

• --description <desc> - Domain description
• --pattern <pattern> - Architecture pattern (basic, eventSourcing, fullDdd)
• --interactive - Enable interactive prompts

Examples:

# Basic domain with entities and repositories
swoft create:domain user-management --pattern basic

# Full DDD with domain services
swoft create:domain order-management --pattern fullDdd

# Event sourcing domain
swoft create:domain inventory --pattern eventSourcing

Application Types

Backend API (--type backend)

• Express.js server with TypeScript
• MongoDB integration
• JWT authentication ready
• Clean architecture structure
• API documentation setup
• Docker configuration

Frontend Web App (--type frontend)

• Next.js 14 with TypeScript
• Modern React patterns
• UI component library ready
• Authentication integration
• Responsive design

Desktop App (--type desktop)

• Electron with React
• TypeScript configuration
• Cross-platform builds
• Native OS integration

CLI Tool (--type cli)

• Commander.js framework
• TypeScript support
• Global installation ready
• Help and documentation

Microservice (--type microservice)

• Lightweight service
• Docker ready
• Health checks
• Metrics integration

Features

Enable features with --features feature1,feature2:

• mongodb - MongoDB database integration with ODM
• auth - JWT authentication with user management
• ai - AI/LLM integration (OpenAI, Anthropic)
• realtime - WebSocket support for real-time features
• storage - File upload and storage handling
• jobs - Background job processing
• docs - API documentation generation

Architecture Patterns

Basic (--pattern basic)

Simple clean architecture with:

• Entities
• Repositories
• Services
• Controllers

Event Sourcing (--pattern eventSourcing)

Advanced pattern with:

• Events
• Aggregates
• Event Store
• Command/Query separation

Full DDD (--pattern fullDdd)

Complete domain-driven design:

• Domain Services
• Value Objects
• Domain Events
• Command/Query handlers

Project Structure

Every Swoft application follows clean architecture:

my-app/
├── apps/
│   └── main/              # Main application
│       ├── src/
│       │   ├── controllers/
│       │   ├── services/
│       │   ├── config/
│       │   └── index.ts
│       └── package.json
├── packages/              # Domain packages
│   └── user-management/
│       ├── src/
│       │   ├── domain/         # Pure business logic
│       │   ├── application/    # Use cases
│       │   ├── infrastructure/ # External concerns
│       │   └── interface/      # Controllers & contracts
│       └── package.json
├── package.json          # Workspace configuration
├── pnpm-workspace.yaml   # pnpm workspace setup
└── turbo.json           # Build orchestration

Development Workflow

1. Create your app:

   npx @swoft/cli create:app my-project --features mongodb,auth
   cd my-project

2. Install dependencies:

   pnpm install

3. Set up environment:

   cp apps/main/.env.example apps/main/.env.local
   # Edit environment variables

4. Start development:

   pnpm dev

5. Add domains as needed:

   npx @swoft/cli create:domain user-management --pattern fullDdd

6. Build for production:

   pnpm build

Interactive Mode

By default, the CLI auto-detects whether to use interactive mode based on the options you provide:

• Non-interactive: When you provide enough options (name + type/features)
• Interactive: When you want to be guided through choices

Force interactive mode:

swoft create:app --interactive

Force non-interactive mode:

swoft create:app my-app --type backend --no-interactive

Getting Help

# Show all commands
swoft --help

# Show detailed help with examples
swoft help

# Command-specific help
swoft create:app --help
swoft create:domain --help

Examples

E-commerce API

swoft create:app ecommerce-api \
  --type backend \
  --features mongodb,auth,jobs,docs \
  --description "E-commerce backend with order processing"

SaaS Dashboard

swoft create:app saas-dashboard \
  --type frontend \
  --description "Multi-tenant SaaS dashboard"

AI Chat Application

swoft create:app ai-chat \
  --type backend \
  --features mongodb,auth,ai,realtime \
  --description "AI-powered chat application"

Data Processing Tool

swoft create:app data-processor \
  --type cli \
  --features jobs,storage \
  --description "CLI tool for data processing"

Requirements

• Node.js ≥ 18.0.0
• pnpm ≥ 8.0.0 (installed automatically)

License

MIT

Contributing

Issues and pull requests welcome at GitHub.

Happy coding with Swoft! 🚀

Built with ❤️ for developers who care about clean architecture