CLI Reference

Complete reference for the Aegis Stack command-line interface.

Global Options

These options work with all commands and must be specified before the command name.

Usage:

aegis [GLOBAL OPTIONS] COMMAND [COMMAND OPTIONS]

Available Options:

--verbose, -v - Enable verbose output (show detailed file operations)
--help - Show help message

Examples:

# Correct: Global flag before command
aegis --verbose init my-project
aegis --verbose add scheduler
aegis -v remove worker

# Incorrect: Global flag after command (will fail)
aegis init my-project --verbose  ❌

What --verbose Shows: - Detailed file operation logs - Template rendering details - Component resolution steps - Dependency installation progress

Quick Start Commands

aegis version

Show the Aegis Stack CLI version.

Usage:

aegis version

Example Output:

Aegis Stack CLI v0.2.1

aegis components

List available components with their status and dependencies.

Usage:

aegis components

Example Output:

AVAILABLE COMPONENTS
========================================

Infrastructure Components
----------------------------------------
  scheduler     - APScheduler-based async task scheduling
  worker        - Pure arq worker with multiple queues (requires: redis)
  database      - SQLite database with SQLModel ORM
  redis         - Redis cache and message broker

aegis services

List available services with their required components.

Usage:

aegis services

Example Output:

AVAILABLE SERVICES
========================================

Authentication Services
----------------------------------------
  auth         - User authentication and authorization with JWT tokens
               Requires components: backend, database

AI & Machine Learning Services
----------------------------------------
  ai           - AI chatbot with PydanticAI engine
               Requires components: backend
               Supports: OpenAI, Anthropic, Google, Groq, Mistral, Cohere

Project Management Commands

aegis init

Create a new Aegis Stack project with your chosen components and services.

Usage:

aegis init PROJECT_NAME [OPTIONS]

Arguments:

PROJECT_NAME - Name of the new project to create (required)

Options:

--components, -c TEXT - Comma-separated list of components
--services, -s TEXT - Comma-separated list of services
--interactive / --no-interactive, -i / -ni - Use interactive selection (default: interactive)
--force, -f - Overwrite existing directory if it exists
--output-dir, -o PATH - Directory to create the project in (default: current directory)
--yes, -y - Skip confirmation prompt

Examples:

# Simple API project
aegis init my-api

# Background processing with scheduler
aegis init task-processor --components scheduler

# User authentication system
aegis init user-app --services auth --components database

# AI chatbot application
aegis init chatbot --services ai

# Full stack with auth and AI
aegis init full-app --services auth,ai --components database,scheduler

# Non-interactive with custom location
aegis init my-app --services auth --components database --no-interactive --output-dir /projects --yes

Available Components:

Component	Status	Description
`scheduler`	✅ Available	APScheduler-based async task scheduling
`scheduler[sqlite]`	✅ Available	Scheduler with SQLite persistence (auto-adds database)
`worker`	✅ Available	arq worker with Redis for background processing (auto-adds redis)
`database`	✅ Available	SQLite database with SQLModel ORM
`redis`	✅ Available	Redis cache and message broker
`cache`	🚧 Coming Soon	Redis-based async caching layer

Available Services:

Service	Status	Description	Required Components
`auth`	✅ Available	User authentication with JWT tokens	backend, database
`ai`	🧪 Experimental	AI chatbot with 7 provider options	backend
`comms`	🧪 Experimental	Email (Resend), SMS & voice (Twilio)	backend

Service Auto-Resolution:

When you select services, required components are automatically added:

--services auth → Auto-adds database component
--services ai → No additional components (backend always included)
--services comms → No additional components (backend always included)
Backend and frontend components are always included in every project

Component Dependencies:

Some components require others and will be auto-added:

worker → Auto-adds redis
scheduler[sqlite] → Auto-adds database

Examples with Auto-Resolution:

# Auth service auto-adds database
aegis init user-app --services auth
# Result: backend + frontend + database + auth service

# Worker auto-adds redis
aegis init task-app --components worker
# Result: backend + frontend + redis + worker

# Scheduler with SQLite auto-adds database
aegis init cron-app --components "scheduler[sqlite]"
# Result: backend + frontend + database + scheduler

aegis add

Add components to an existing Aegis Stack project.

Usage:

aegis add COMPONENTS [OPTIONS]

Arguments:

COMPONENTS - Comma-separated list of components to add

Options:

--backend, -b TEXT - Scheduler backend: 'memory' (default) or 'sqlite' (enables persistence)
--interactive, -i - Use interactive component selection
--project-path, -p PATH - Path to the Aegis Stack project (default: current directory)
--yes, -y - Skip confirmation prompt

Examples:

# Add scheduler with memory backend
aegis add scheduler

# Add scheduler with SQLite persistence
aegis add scheduler --backend sqlite
# or using bracket syntax
aegis add "scheduler[sqlite]"

# Add worker (auto-includes redis)
aegis add worker

# Add multiple components
aegis add database,scheduler

# Add to specific project
aegis add scheduler --project-path ../my-project

# Interactive mode
aegis add --interactive

How It Works:

Validates project was generated with Copier
Checks component dependencies (auto-adds required components)
Renders component templates with Jinja2
Copies files to project (skips existing files)
Updates .copier-answers.yml with new configuration
Regenerates shared files (docker-compose.yml, pyproject.toml)
Runs uv sync to install new dependencies
Runs make fix to format code

Notes:

Components added incrementally without breaking existing code
Shared files automatically regenerated with backups
Changes are non-destructive (commit before running for easy rollback)
Use --verbose flag to see detailed operation logs

aegis add-service

Add services to an existing Aegis Stack project.

Usage:

aegis add-service SERVICES [OPTIONS]

Arguments:

SERVICES - Comma-separated list of services to add

Options:

--interactive, -i - Use interactive service selection
--project-path, -p PATH - Path to the Aegis Stack project (default: current directory)
--yes, -y - Skip confirmation prompt

Examples:

# Add auth service (auto-adds database if not present)
aegis add-service auth

# Add AI service
aegis add-service ai

# Add multiple services
aegis add-service auth,ai

# Interactive service selection
aegis add-service --interactive

# Non-interactive with auto-yes
aegis add-service auth --yes --project-path ../my-project

Service Auto-Resolution:

Services automatically add their required components if missing:

auth → Requires database component (auto-added if missing)
ai → Requires backend component (always present)

Post-Addition Setup:

After adding services, follow these steps:

For Auth Service:

make migrate                       # Apply auth database migrations
my-project auth create-test-users  # Create test users for development
my-project auth list-users         # Verify users created

For AI Service:

Configure provider in .env:

AI_PROVIDER=public  # Options: public, openai, anthropic, google, groq, mistral, cohere

# For paid providers, add API key:
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

Test the AI service:

my-project ai chat                 # Start interactive chat
my-project ai providers list       # See all available providers

Important Notes:

Only works with Copier-generated projects (default since v0.2.0)
Requires git repository (for change tracking)
Services require their dependencies - they will be auto-added
Review changes with git diff before committing

See Generated Project CLI section below for full command reference.

aegis remove

Remove components from an existing Aegis Stack project.

Usage:

aegis remove COMPONENTS [OPTIONS]

Arguments:

COMPONENTS - Comma-separated list of components to remove

Options:

--interactive, -i - Use interactive component selection
--project-path, -p PATH - Path to the Aegis Stack project (default: current directory)
--yes, -y - Skip confirmation prompt

Examples:

# Remove scheduler component
aegis remove scheduler

# Remove multiple components
aegis remove scheduler,worker

# Interactive mode
aegis remove --interactive

How It Works:

Validates project was generated with Copier
Checks component is currently enabled
Deletes component files and directories
Cleans up empty parent directories
Updates .copier-answers.yml to disable component
Regenerates shared files (docker-compose.yml, pyproject.toml)
Runs uv sync to clean up unused dependencies
Runs make fix to format code

Important Warnings:

THIS OPERATION DELETES FILES - Commit your changes to git first
Core components (backend, frontend) cannot be removed
Removing scheduler with SQLite persistence leaves data/scheduler.db intact
Shared template files are regenerated (backups created automatically)
Redis is auto-removed when worker is removed (no standalone functionality)

aegis update

Update an existing Copier-based project to the latest template version.

Usage:

aegis update [OPTIONS]

Options:

--project-path PATH - Path to project to update (default: current directory)
--to-version TEXT - Update to specific template version (default: latest)
--force, -f - Accept all template changes automatically
--yes, -y - Skip confirmation prompt
--dry-run - Preview changes without applying them

Examples:

# Update current project to latest template
aegis update

# Update specific project
aegis update --project-path ../my-project

# Update to specific template version
aegis update --to-version 0.2.0

# Preview changes without applying
aegis update --dry-run

# Auto-accept all updates
aegis update --force --yes

How It Works:

Validates project was generated with Copier
Checks current template version from .copier-answers.yml
Fetches latest template version (or specified version)
Compares current files with template updates
Shows diff of changes to be applied
Prompts for conflict resolution
Applies updates and creates backup files
Runs uv sync to update dependencies
Runs make fix to format updated code

What Gets Updated:

✅ Template infrastructure files
✅ Shared files (docker-compose.yml, pyproject.toml, Makefile)
✅ Component implementations (if unmodified)
✅ Test infrastructure
✅ Documentation templates

What's Preserved:

✅ Your custom business logic
✅ Your environment variables (.env)
✅ Your database migrations
✅ Your custom models and services
✅ Files you've modified (marked as conflicts)

Important Notes:

Cookiecutter projects cannot use this command - Copier only
Always commit before updating: git add . && git commit -m "Pre-update checkpoint"
Test after updating: Run make check to verify everything works
Use --dry-run first to preview changes

Generated Project CLI

When you add services to a project, they install their own CLI commands as entry point scripts. These commands are available after running uv sync in your generated project.

Script Installation:

All generated projects get a CLI script matching the project name:

# If project is named "my-app"
my-app --help

# If project is named "chatbot"
chatbot --help

Component CLIs

Components that add CLI capabilities to your generated projects:

Scheduler - my-app tasks

Manage scheduled tasks with persistent job tracking:

my-app tasks list       # List all scheduled jobs
my-app tasks stats      # View scheduler statistics
my-app tasks history    # View execution history

→ Complete Scheduler CLI Reference

Worker - Native arq CLI

Background task processing with Redis-backed queues:

arq my_project.components.worker.WorkerSettings  # Start worker
arq --watch my_project.components.worker.WorkerSettings  # Auto-reload

→ Complete Worker CLI Reference

Service CLIs

Services that add CLI capabilities to your generated projects:

Auth Service - my-app auth

User management and testing utilities:

my-app auth create-test-user   # Create single test user
my-app auth create-test-users  # Create multiple test users
my-app auth list-users         # List all users

→ Complete Auth CLI Reference

AI Service - my-app ai

Multi-provider AI chat interface with conversation management:

my-app ai chat                 # Interactive chat session
my-app ai chat send "Hello"    # Send single message
my-app ai config show          # View AI configuration
my-app ai providers list       # List all 7 AI providers

→ Complete AI CLI Reference

Project Structure

Projects created with aegis init follow this structure:

my-project/
├── app/
│   ├── components/
│   │   ├── backend/        # FastAPI backend
│   │   ├── frontend/       # Flet frontend
│   │   ├── scheduler.py    # APScheduler (if included)
│   │   ├── worker/         # arq worker queues (if included)
│   │   └── database.py     # Database setup (if included)
│   ├── core/              # Framework utilities
│   ├── services/          # Business logic
│   ├── cli/               # CLI commands (if services added)
│   └── integrations/      # App composition
├── tests/                 # Test suite
├── docs/                  # Documentation
├── data/                  # SQLite databases (if database included)
├── pyproject.toml         # Project configuration
├── Dockerfile             # Container definition
├── docker-compose.yml     # Multi-service orchestration
├── Makefile              # Development commands
└── .env.example          # Environment template

Development Workflow

After creating a project:

cd my-project
uv sync                    # Install dependencies and create virtual environment
source .venv/bin/activate  # Activate virtual environment (important!)
cp .env.example .env       # Configure environment (edit API keys, etc.)
make serve                 # Start development server
make test                  # Run test suite
make check                 # Run all quality checks (lint + typecheck + test)

Evolving Your Project

# Add components as you need them
aegis add scheduler
aegis add worker

# Add services for new features
aegis add-service auth
aegis add-service ai

# Remove components you don't need
aegis remove scheduler

# Update to latest template version
aegis update

# Always commit before making changes
git add . && git commit -m "Add scheduler component"

Best Practices

Commit before evolving: Always commit your work before adding/removing components
Use verbose mode: Add --verbose flag to see detailed operations
Test after changes: Run make check after adding/removing components
Review diffs: Use git diff to see what changed after operations
Update regularly: Keep your project in sync with latest template via aegis update

Environment

The CLI respects these environment variables:

Standard Python environment variables
UV environment variables (for dependency management)
Project-specific variables (when running generated CLI commands)