Acton CLI

Production-ready CLI for scaffolding and managing backend services built with the acton-service framework.

Features

✅ Fully Implemented:

• Interactive and non-interactive service creation
• Comprehensive command structure
• Service scaffolding with multiple features
• Template-based code generation
• Git integration
• Automatic code formatting
• acton service add endpoint - Add HTTP endpoints ✨ NEW
• acton service add worker - Add background workers ✨ NEW
• acton service generate deployment - Generate K8s manifests ✨ NEW

🚧 Planned:

• acton service add grpc - Add gRPC services
• acton service add middleware - Add custom middleware
• acton service add version - Add API versions
• acton service validate - Validate service quality
• acton service generate config - Generate configuration
• acton service generate proto - Generate proto files
• acton service dev - Development tools

Installation

Build from source:

cargo build --release -p acton-cli

The binary will be available at target/release/acton.

Usage

Command Structure

acton
├── service
│   ├── new <service-name>          # Create new service
│   ├── add
│   │   ├── endpoint                # Add HTTP endpoint
│   │   ├── grpc                    # Add gRPC service
│   │   ├── worker                  # Add background worker
│   │   ├── middleware              # Add middleware
│   │   └── version                 # Add API version
│   ├── generate
│   │   ├── deployment              # Generate deployment configs
│   │   ├── config                  # Generate config file
│   │   └── proto                   # Generate proto file
│   ├── validate                    # Validate service
│   └── dev
│       ├── run                     # Run development server
│       ├── health                  # Check service health
│       └── logs                    # View logs
└── [future top-level commands]

Creating a New Service

Interactive Mode (Beginner-Friendly)

acton service new my-service

This will prompt you for:

• Service type (HTTP/gRPC/Both)
• Database support
• Caching support
• Event streaming
• Observability features

Non-Interactive Mode (Fast)

acton service new my-service \
    --http \
    --database postgres \
    --cache redis \
    --observability

Quick Start (Minimal)

acton service new my-service --yes

Creates a minimal HTTP service with defaults.

Available Options

--http                 Enable HTTP REST API (default)
--grpc                 Enable gRPC service
--full                 Enable both HTTP and gRPC
--database <TYPE>      Add database (postgres)
--cache <TYPE>         Add caching (redis)
--events <TYPE>        Add event streaming (nats)
--auth <TYPE>          Add authentication (jwt)
--observability        Enable OpenTelemetry tracing
--resilience           Enable circuit breaker, retry, etc.
--rate-limit           Enable rate limiting
--openapi              Generate OpenAPI/Swagger
--template <NAME>      Use organization template
--path <DIR>           Create in specific directory
--no-git               Skip git initialization
-i, --interactive      Interactive mode
-y, --yes              Accept all defaults
--dry-run              Show what would be generated

Examples

Simple HTTP API

acton service new todo-api --yes
cd todo-api
cargo run

Full-Stack Service

acton service new user-service \
    --http \
    --grpc \
    --database postgres \
    --cache redis \
    --events nats \
    --auth jwt \
    --observability \
    --resilience

HTTP + gRPC Dual Protocol

acton service new gateway \
    --full \
    --database postgres

Generated Project Structure

my-service/
├── Cargo.toml                 # Dependencies with correct features
├── config.toml                # Complete configuration
├── Dockerfile                 # Multi-stage build
├── .dockerignore
├── .gitignore
├── README.md                  # Generated documentation
├── build.rs                   # Proto compilation (if gRPC)
├── proto/                     # Proto files (if gRPC)
└── src/
    ├── main.rs               # Service entry point
    └── handlers.rs           # HTTP handlers (if HTTP)

Design Philosophy

The Acton CLI follows these principles:

1. Progressive Disclosure - Simple by default, powerful when needed
2. Safe by Default - Prevent mistakes through validation
3. Educational - Generated code teaches framework patterns
4. Production-Ready - Every service meets operational standards
5. Discoverable - Self-documenting with excellent help

User Personas Supported

• Beginners - Interactive wizard, educational output
• Intermediate - Fast scaffolding with flags
• Senior Engineers - Organization templates (coming soon)
• DevOps/SRE - Deployment validation (coming soon)

Architecture

The CLI is built with:

• Command parsing: clap with derive macros
• Interactivity: dialoguer for prompts
• Templating: handlebars for code generation
• Progress: indicatif for progress bars
• Colors: colored and console for output

Development

Project Structure

acton-cli/
├── src/
│   ├── main.rs                    # Entry point
│   ├── commands/
│   │   └── service/               # Service commands
│   │       ├── new.rs            # ✅ Implemented
│   │       ├── add/              # 🚧 Stubs
│   │       ├── generate/         # 🚧 Stubs
│   │       ├── validate.rs       # 🚧 Stub
│   │       └── dev/              # 🚧 Stubs
│   ├── templates/                 # Code generation templates
│   │   ├── service.rs            # ✅ main.rs templates
│   │   ├── cargo_toml.rs         # ✅ Cargo.toml generation
│   │   ├── config.rs             # ✅ config.toml generation
│   │   ├── handlers.rs           # ✅ Handler templates
│   │   └── deployment.rs         # ✅ Dockerfile templates
│   ├── utils/                     # Utilities
│   │   ├── format.rs             # Name conversions
│   │   ├── git.rs                # Git operations
│   │   └── cargo.rs              # Cargo operations
│   └── validator/                 # 🚧 Validation logic
└── Cargo.toml

Building

# Development build
cargo build -p acton-cli

# Release build
cargo build --release -p acton-cli

# Run directly
cargo run -p acton-cli -- service new test-api --yes

Testing

# Create a test service
./target/debug/acton service new test-service --yes --path /tmp

# Verify it was created
ls -la /tmp/test-service

# Clean up
rm -rf /tmp/test-service

Command Examples

Adding HTTP Endpoints

# Add a GET endpoint
acton service add endpoint GET /users --version v1

# Add a POST endpoint with full options
acton service add endpoint POST /users \
    --handler create_user \
    --model User \
    --validate \
    --openapi

# Preview what would be generated
acton service add endpoint GET /users/:id --dry-run

Adding Background Workers

# Add a NATS worker
acton service add worker email-worker \
    --source nats \
    --stream emails \
    --subject "emails.>"

# Add a Redis Stream worker
acton service add worker notification-worker \
    --source redis-stream \
    --stream notifications

# Preview worker generation
acton service add worker my-worker --source nats --stream events --dry-run

Generating Deployments

# Generate basic Kubernetes manifests
acton service generate deployment

# Generate with autoscaling and monitoring
acton service generate deployment \
    --hpa \
    --monitoring \
    --replicas 3

# Generate complete production setup
acton service generate deployment \
    --namespace production \
    --hpa \
    --monitoring \
    --ingress \
    --tls \
    --registry gcr.io/myproject \
    --image-tag v1.0.0

# Preview deployment manifests
acton service generate deployment --dry-run

Next Steps

To continue implementation:

1. Add gRPC Command - gRPC service generation
2. Add Middleware Command - Custom middleware handlers
3. Add Version Command - API versioning support
4. Validate Command - Quality checks and scoring
5. Generate Config Command - Configuration file generation
6. Dev Commands - Development server, health checks, logs

Contributing

The CLI is designed to be extended. Key extension points:

• Templates - Add new code templates in src/templates/
• Commands - Add new commands in src/commands/service/
• Validators - Add validation rules in src/validator/
• Utilities - Add helper functions in src/utils/

License

MIT