CLI Options Reference

This document provides a comprehensive reference for all Azu CLI commands, options, and flags.

Command Structure

All Azu CLI commands follow this structure:

azu <command> [subcommand] [options] [arguments]

Global Options

These options are available for all commands:

Option	Short	Description	Example
--help	-h	Show help for the command	azu --help
--version	-v	Show version information	azu --version
--verbose	-V	Enable verbose output	azu generate --verbose
--quiet	-q	Suppress output except errors	azu serve --quiet
--config	-c	Specify configuration file	azu --config=./custom.yml
--log-level	-l	Set log level	azu --log-level=debug
--color		Enable/disable colored output	azu --color=false

Project Commands

azu new

Create a new Azu project.

azu new <project_name> [options]

Option	Description	Default	Example
--framework	Framework to use	azu	--framework=azu
--orm	ORM to use	cql	--orm=cql
--template	Project template	web	--template=api
--database	Database adapter	postgresql	--database=mysql
--skip-git	Skip Git initialization	false	--skip-git
--skip-install	Skip dependency installation	false	--skip-install
--force	Overwrite existing directory	false	--force

Examples:

# Create basic web project
azu new myapp

# Create API project with MySQL
azu new myapi --template=api --database=mysql

# Create project with custom framework
azu new myapp --framework=custom --skip-git

azu init

Initialize Azu in an existing project.

azu init [options]

Option	Description	Default	Example
--framework	Framework to use	azu	--framework=azu
--orm	ORM to use	cql	--orm=cql
--database	Database adapter	postgresql	--database=mysql
--force	Overwrite existing config	false	--force

Examples:

# Initialize with defaults
azu init

# Initialize with specific ORM
azu init --orm=cql --database=postgresql

Generation Commands

azu generate

Generate code components.

azu generate <generator> <name> [options]

Common Generator Options

Option	Description	Default	Example
--namespace	Custom namespace	Project namespace	--namespace=Admin
--skip-spec	Skip test generation	false	--skip-spec
--skip-docs	Skip documentation	false	--skip-docs
--template	Custom template	Default template	--template=custom
--force	Overwrite existing files	false	--force

Endpoint Generator

azu generate endpoint <name> [options]

Option	Description	Default	Example
--methods	HTTP methods to generate	index,show,new,create,edit,update,destroy	--methods=index,show,create
--route-prefix	Route prefix	/	--route-prefix=/api/v1
--response-format	Response format	json	--response-format=html
--auth	Require authentication	false	--auth
--authorization	Add authorization	false	--authorization
--contract	Generate contracts	true	--skip-contract
--page	Generate pages	false	--page

Examples:

# Generate basic endpoint
azu generate endpoint users

# Generate API endpoint
azu generate endpoint users --methods=index,show,create,update,destroy --response-format=json

# Generate with authentication
azu generate endpoint users --auth --authorization

Model Generator

azu generate model <name> [fields] [options]

Option	Description	Default	Example
--orm	ORM framework	cql	--orm=cql
--migration	Generate migration	true	--skip-migration
--timestamps	Include timestamps	true	--skip-timestamps
--soft-deletes	Include soft deletes	false	--soft-deletes
--validations	Add validations	true	--skip-validations
--associations	Generate associations	false	--associations

Field Types:

• string - String field

• text - Text field

• integer - Integer field

• float - Float field

• decimal - Decimal field

• boolean - Boolean field

• datetime - DateTime field

• date - Date field

• time - Time field

• json - JSON field

• uuid - UUID field

Examples:

# Generate basic model
azu generate model User email:string name:string

# Generate model with associations
azu generate model Post title:string content:text user:belongs_to

# Generate model with custom options
azu generate model Product name:string price:decimal --soft-deletes --validations

Service Generator

azu generate service <name> [options]

Option	Description	Default	Example
--methods	Service methods	create,update,destroy,find,list	--methods=create,update
--interface	Generate interface	true	--skip-interface
--transactions	Include transactions	true	--skip-transactions
--error-handling	Error handling approach	exceptions	--error-handling=results
--dependency-injection	Use dependency injection	true	--skip-di

Examples:

# Generate basic service
azu generate service UserService

# Generate service with custom methods
azu generate service PaymentService --methods=process,refund,cancel

Page Generator

azu generate page <name> [options]

Option	Description	Default	Example
--template-engine	Template engine	jinja	--template-engine=ecr
--layout	Layout template	layout	--layout=admin
--css-framework	CSS framework	bootstrap	--css-framework=tailwind
--js-framework	JavaScript framework	vanilla	--js-framework=alpine
--forms	Include forms	true	--skip-forms
--pagination	Include pagination	false	--pagination

Examples:

# Generate basic page
azu generate page users/index

# Generate page with custom template engine
azu generate page users/show --template-engine=ecr --css-framework=tailwind

Contract Generator

azu generate contract <name> [options]

Option	Description	Default	Example
--fields	Contract fields	None	--fields=email:string,name:string
--validations	Add validations	true	--skip-validations
--framework	Validation framework	crystal	--framework=custom

Examples:

# Generate basic contract
azu generate contract CreateUser

# Generate contract with fields
azu generate contract UpdateUser --fields=email:string,name:string,age:integer

Component Generator

azu generate component <name> [options]

Option	Description	Default	Example
--type	Component type	ui	--type=form
--template-engine	Template engine	jinja	--template-engine=ecr
--css-framework	CSS framework	bootstrap	--css-framework=tailwind
--props	Include props	true	--skip-props
--slots	Include slots	false	--slots
--events	Include events	false	--events

Examples:

# Generate basic component
azu generate component UserCard

# Generate form component
azu generate component UserForm --type=form --props --events

Middleware Generator

azu generate middleware <name> [options]

Option	Description	Default	Example
--type	Middleware type	custom	--type=authentication
--before	Execute before	None	--before=auth
--after	Execute after	None	--after=logging
--config	Include configuration	true	--skip-config

Examples:

# Generate basic middleware
azu generate middleware RateLimiting

# Generate authentication middleware
azu generate middleware AuthMiddleware --type=authentication --before=auth

Migration Generator

azu generate migration <name> [options]

Option	Description	Default	Example
--table	Table name	Inferred from name	--table=users
--fields	Migration fields	None	--fields=email:string,name:string
--reversible	Make migration reversible	true	--skip-reversible

Examples:

# Generate basic migration
azu generate migration create_users

# Generate migration with fields
azu generate migration add_fields_to_users --fields=email:string,name:string

Scaffold Generator

azu generate scaffold <name> [fields] [options]

Option	Description	Default	Example
--skip-model	Skip model generation	false	--skip-model
--skip-endpoint	Skip endpoint generation	false	--skip-endpoint
--skip-page	Skip page generation	false	--skip-page
--skip-contract	Skip contract generation	false	--skip-contract
--skip-service	Skip service generation	false	--skip-service

Examples:

# Generate full scaffold
azu generate scaffold User email:string name:string

# Generate scaffold without pages
azu generate scaffold Product name:string price:decimal --skip-page

Database Commands

azu db

Database management commands.

azu db <subcommand> [options]

azu db create

Create database.

azu db create [options]

Option	Description	Default	Example
--adapter	Database adapter	From config	--adapter=postgresql
--url	Database URL	From config	--url=postgresql://localhost/myapp
--force	Force creation	false	--force

azu db drop

Drop database.

azu db drop [options]

Option	Description	Default	Example
--adapter	Database adapter	From config	--adapter=postgresql
--url	Database URL	From config	--url=postgresql://localhost/myapp
--force	Force drop	false	--force

azu db migrate

Run database migrations.

azu db migrate [options]

Option	Description	Default	Example
--version	Target version	Latest	--version=20231201000000
--adapter	Database adapter	From config	--adapter=postgresql
--dry-run	Show what would be run	false	--dry-run
--verbose	Show detailed output	false	--verbose

azu db rollback

Rollback database migrations.

azu db rollback [options]

Option	Description	Default	Example
--version	Target version	Previous	--version=20231101000000
--steps	Number of steps	1	--steps=3
--adapter	Database adapter	From config	--adapter=postgresql
--dry-run	Show what would be run	false	--dry-run

azu db seed

Seed database with data.

azu db seed [options]

Option	Description	Default	Example
--file	Seed file	seed.cr	--file=users.cr
--adapter	Database adapter	From config	--adapter=postgresql
--force	Force seeding	false	--force

azu db reset

Reset database (drop, create, migrate, seed).

azu db reset [options]

Option	Description	Default	Example
--adapter	Database adapter	From config	--adapter=postgresql
--skip-seed	Skip seeding	false	--skip-seed
--force	Force reset	false	--force

azu db status

Show migration status.

azu db status [options]

Option	Description	Default	Example
--adapter	Database adapter	From config	--adapter=postgresql
--format	Output format	table	--format=json

azu db new_migration

Generate new migration.

azu db new_migration <name> [options]

Option	Description	Default	Example
--table	Table name	Inferred from name	--table=users
--fields	Migration fields	None	--fields=email:string,name:string
--reversible	Make migration reversible	true	--skip-reversible

Development Commands

azu serve

Start development server.

azu serve [options]

Option	Description	Default	Example
--host	Server host	localhost	--host=0.0.0.0
--port	Server port	3000	--port=8080
--workers	Number of workers	1	--workers=4
--reload	Enable hot reload	false	--reload
--watch	Watch directories	src/	--watch=src/endpoints,src/models
--ssl	Enable SSL	false	--ssl
--ssl-cert	SSL certificate	None	--ssl-cert=cert.pem
--ssl-key	SSL private key	None	--ssl-key=key.pem
--env	Environment	development	--env=production

Examples:

# Start basic server
azu serve

# Start with hot reload
azu serve --reload --port=8080

# Start with SSL
azu serve --ssl --ssl-cert=cert.pem --ssl-key=key.pem

azu dev

Development workflow commands.

azu dev <subcommand> [options]

azu dev console

Start interactive console.

azu dev console [options]

Option	Description	Default	Example
--env	Environment	development	--env=test
--load	Load specific files	None	--load=src/models/*.cr

azu dev test

Run tests.

azu dev test [options]

Option	Description	Default	Example
--framework	Test framework	spec	--framework=minitest
--pattern	Test pattern	spec/**/*_spec.cr	--pattern=spec/models/*
--parallel	Run tests in parallel	false	--parallel
--coverage	Generate coverage	false	--coverage
--verbose	Verbose output	false	--verbose

azu dev lint

Run linter.

azu dev lint [options]

Option	Description	Default	Example
--tool	Linting tool	ameba	--tool=crystal
--rules	Specific rules	All rules	--rules=Style,Performance
--fix	Auto-fix issues	false	--fix
--format	Output format	text	--format=json

azu dev format

Format code.

azu dev format [options]

Option	Description	Default	Example
--check	Check only	false	--check
--files	Specific files	All Crystal files	--files=src/endpoints/*.cr

Configuration Commands

azu config

Configuration management.

azu config <subcommand> [options]

azu config show

Show current configuration.

azu config show [options]

Option	Description	Default	Example
--format	Output format	yaml	--format=json
--env	Environment	Current	--env=production
--section	Specific section	All	--section=database

azu config validate

Validate configuration.

azu config validate [options]

Option	Description	Default	Example
--env	Environment	Current	--env=production
--strict	Strict validation	false	--strict

azu config env

Environment variable management.

azu config env [options]

Option	Description	Default	Example
--list	List all variables	false	--list
--show	Show current values	false	--show
--set	Set variable	None	--set=AZU_LOG_LEVEL=debug
--unset	Unset variable	None	--unset=AZU_LOG_LEVEL

Utility Commands

azu help

Show help information.

azu help [command]

azu version

Show version information.

azu version [options]

Option	Description	Default	Example
--format	Output format	text	--format=json
--check	Check for updates	false	--check

Environment Variables

Core Variables

Variable	Description	Default
AZU_CONFIG_PATH	Configuration file path	./azu.yml
AZU_LOG_LEVEL	Log level	info
AZU_ENV	Environment	development

Database Variables

Variable	Description	Default
AZU_DATABASE_URL	Database connection URL	None
AZU_DATABASE_HOST	Database host	localhost
AZU_DATABASE_PORT	Database port	5432
AZU_DATABASE_NAME	Database name	None
AZU_DATABASE_USER	Database username	None
AZU_DATABASE_PASSWORD	Database password	None

Server Variables

Variable	Description	Default
AZU_SERVER_HOST	Server host	localhost
AZU_SERVER_PORT	Server port	3000
AZU_SERVER_WORKERS	Number of workers	1
AZU_SERVER_RELOAD	Enable hot reload	false

Exit Codes

Code	Description
0	Success
1	General error
2	Configuration error
3	Database error
4	Generation error
5	Validation error
6	Network error
7	Permission error

Examples

Complete Workflow

# Create new project
azu new myapp --framework=azu --orm=cql

# Generate scaffold
azu generate scaffold User email:string name:string

# Setup database
azu db create
azu db migrate
azu db seed

# Start development server
azu serve --reload --port=8080

Advanced Generation

# Generate API endpoint with authentication
azu generate endpoint users \
  --methods=index,show,create,update,destroy \
  --response-format=json \
  --auth \
  --authorization

# Generate model with associations
azu generate model Post \
  title:string \
  content:text \
  user:belongs_to \
  --validations \
  --soft-deletes

# Generate service with custom methods
azu generate service PaymentService \
  --methods=process,refund,cancel \
  --interface \
  --transactions

Database Management

# Create and setup database
azu db create
azu db migrate
azu db seed

# Check migration status
azu db status

# Rollback last migration
azu db rollback

# Reset database
azu db reset --skip-seed

Development Workflow

# Run tests
azu dev test --parallel --coverage

# Run linter
azu dev lint --fix

# Format code
azu dev format

# Start console
azu dev console --env=development