npm package: @kartius/cli
Description: CLI tools for Kartius e-commerce framework
Author: Kartius Team
Latest version: 1.0.0

# Kartius CLI

Beautiful, interactive CLI tools for the Kartius e-commerce framework.

## Features

✨ **Interactive Prompts** - Beautiful, user-friendly prompts using @clack/prompts  
🎨 **Colorful Output** - Gradient ASCII art and color-coded messages  
🚀 **Quick Setup** - Scaffold a new project in under 2 minutes  
🔌 **Plugin Management** - Create, install, and manage plugins easily  
⚡ **Code Generation** - Generate resolvers, services, entities, and more  
🗄️ **Database Migrations** - Create and run migrations with ease  
🧪 **Testing Tools** - Built-in test runner integration  

## Installation

### Create a New Project

```bash
# Using npm
npm create kartius@latest my-shop

# Using pnpm (recommended)
pnpm create kartius my-shop

# Using yarn
yarn create kartius my-shop

# With specific template
pnpm create kartius my-shop --template advanced
```

### Install CLI in Existing Project

```bash
pnpm add -D @kartius/cli
```

## Usage

### Interactive Mode

Simply run `kartius` without arguments to see an interactive menu:

```bash
kartius
```

### Development Commands

```bash
# Start development server
kartius dev
kartius dev --port 4000
kartius dev --inspect  # Enable Node.js debugger

# Start worker process
kartius worker
kartius worker --concurrency 10
kartius worker --queues email,search

# Build for production
kartius build
kartius build --watch
```

### Plugin Management

```bash
# Create a new plugin
kartius plugin create
kartius plugin create loyalty-system

# List installed plugins
kartius plugin list

# Install plugin from npm
kartius plugin install @kartius/plugin-stripe

# Remove plugin
kartius plugin remove @kartius/plugin-stripe

# Validate plugin structure
kartius plugin validate loyalty-system
```

### Code Generation

```bash
# Generate GraphQL resolver
kartius generate resolver Product

# Generate service
kartius generate service Inventory

# Generate entity/model
kartius generate entity Review

# Generate complete CRUD module
kartius generate module Wishlist

# Generate event handler
kartius generate handler OrderPlacedHandler

# Generate job processor
kartius generate processor EmailProcessor
```

### Database Migrations

```bash
# Create a new migration
kartius migrate create AddLoyaltyPoints

# Run pending migrations
kartius migrate run

# Revert last migration
kartius migrate revert

# Show migration status
kartius migrate status
```

### Testing

```bash
# Run all tests
kartius test

# Run tests in watch mode
kartius test --watch

# Run specific test suite
kartius test --filter ProductService

# Generate coverage report
kartius test --coverage
```

### Information Commands

```bash
# Show version
kartius --version

# Show help
kartius --help

# Show configuration
kartius info config

# Show API routes
kartius info routes

# System health check
kartius info doctor
```

## Project Structure

When you create a new project, you'll get:

```
my-shop/
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── docker-compose.yml
├── src/
│   ├── index.ts
│   ├── worker.ts
│   ├── kartius.config.ts
│   ├── plugins/
│   ├── migrations/
│   ├── entities/
│   ├── services/
│   ├── resolvers/
│   └── controllers/
└── email-templates/
```

## Templates

### Starter (Recommended)
- Basic setup with essential plugins
- PostgreSQL/MySQL/SQLite support
- Docker Compose for development
- Email plugin pre-configured

### Advanced
- Multiple pre-configured plugins
- Example data and seed scripts
- Advanced features enabled
- Production-ready setup

### Minimal
- Bare bones setup
- Add plugins manually
- Maximum flexibility
- Smallest footprint

## Plugin Development

Create a new plugin:

```bash
kartius plugin create my-plugin
```

This generates:

```
src/plugins/my-plugin/
├── index.ts
├── package.json
├── README.md
├── services/
├── handlers/
├── processors/
└── migrations/
```

Example plugin structure:

```typescript
import { Plugin } from '@kartius/core';
import { MyService } from './services/my.service';

@Plugin({
  name: 'my-plugin',
  version: '1.0.0',
  providers: [MyService],
})
export class MyPlugin {
  static init(options?: MyPluginOptions) {
    return {
      plugin: MyPlugin,
      options,
    };
  }
}
```

## Configuration

The CLI reads from `src/kartius.config.ts`:

```typescript
import { KartiusConfig } from '@kartius/core';
import { EmailPlugin } from '@kartius/plugin-email';

export const config: KartiusConfig = {
  apiOptions: {
    port: 3000,
    adminApiPath: 'admin-api',
    shopApiPath: 'shop-api',
  },
  
  dbOptions: {
    type: 'postgres',
    host: 'localhost',
    port: 5432,
    database: 'kartius_shop',
  },
  
  plugins: [
    EmailPlugin.init({
      transport: { type: 'smtp', host: 'localhost', port: 1025 },
    }),
  ],
};
```

## Environment Variables

Create a `.env` file:

```env
PORT=3000

DB_HOST=localhost
DB_PORT=5432
DB_NAME=kartius_shop
DB_USER=postgres
DB_PASSWORD=postgres

REDIS_HOST=localhost
REDIS_PORT=6379

SMTP_HOST=localhost
SMTP_PORT=1025
```

## Docker Support

The CLI generates a `docker-compose.yml` for development:

```yaml
version: "3.8"

services:
  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: kartius_shop
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"
      - "8025:8025"
```

Start services:

```bash
docker-compose up -d
```

## Troubleshooting

### Port Already in Use

```bash
kartius dev --port 4000
```

### Database Connection Issues

Check your `.env` file and ensure database is running:

```bash
docker-compose ps
```

### Migration Failures

Reset database (⚠️ **destroys all data**):

```bash
kartius migrate reset --force
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md).

## License

MIT © Kartius Team

## Support

- 📖 [Documentation](https://docs.kartius.dev)
- 💬 [Discord Community](https://discord.gg/kartius)
- 🐛 [Issue Tracker](https://github.com/kartius/kartius/issues)
- 📧 [Email Support](mailto:support@kartius.dev)

---

Made with ❤️ by the Kartius team