Azu CLI

Command-line tool for the Azu Toolkit: it creates Azu projects, generates code (models, endpoints, scaffolds, channels, session authentication, jobs and more), manages the CQL database and runs a development server.

Features

• Project generator - azu new creates a web, API or CLI project; --docker adds a multi-stage Dockerfile, --ci a GitHub Actions workflow
• Generators - models, endpoints, scaffolds (CRUD), migrations, services, requests, pages, channels, session authentication, jobs and more
• Database commands - create, migrate, rollback, seed, reset, status (CQL migrations)
• Development server - azu dev rebuilds (not a release build) and restarts when sources change; azu serve is the older --production variant
• Diagnostics - azu routes lists the routes, azu doctor checks the environment, azu console opens Crystal's interpreter with the app loaded
• JoobQ and sessions - jobs:* and session:* commands
• OpenAPI - export a spec from the code, or generate code from a spec

Installation

git clone https://github.com/azutoolkit/azu_cli
cd azu_cli
shards install
shards build
sudo make install

Quick Start

# Create a new project (SQLite by default: no database server needed; `--db postgresql` or `--db mysql` for a server)
azu new my_app
cd my_app

# Generate a CRUD resource, create and migrate the database
azu generate scaffold Post title:string content:text published:bool
azu db:setup

# Start the development server
azu dev

Visit http://localhost:4000/posts to see your application.

Commands

Run azu help for the list (azu --help and azu --version are not options: use azu help and azu version).

Generators

azu generate model User name:string email:string
azu generate scaffold Product name:string price:float64
azu generate channel Chat
azu generate auth
azu generate job SendEmail user_id:int64

Delivery

Generated web apps use daisyUI + Tailwind CSS, with ready-to-run local styles, light/dark themes, responsive navigation, CRUD forms, empty states and account avatars. Scaffolds and web index endpoints automatically add their sections to the shared navigation. Customize Jinja templates directly; use npm ci and npm run watch:css when changing styles. See Generated UI and Navigation.

azu new my_app --docker               # Dockerfile + .dockerignore (production image, non-root, /health check)
azu new my_app --no-ci                # skip the GitHub Actions workflow

scripts/e2e_generated_app.sh (CI) and scripts/e2e_docker.sh (needs a docker daemon) build and boot generated projects.

For real browser acceptance, install Python Playwright (python3 -m pip install playwright), Chromium, Redis and Node.js 20+, then run sh scripts/e2e_browser_app.sh after building bin/azu. Set CHROMIUM_PATH if Chromium is not on PATH. It generates a disposable SQLite web app, rebuilds CSS before generating its pages, and clicks through navigation, product CRUD, mobile forms, registration, login and logout; checks chat broadcasts with browser WebSockets; and verifies incremental migration rollback/reapply, idempotence and session/data persistence across a server rebuild/restart. The retained temporary directory contains the app, screenshots, logs and a report. The private Playwright trace contains synthetic session/CSRF cookies; do not publish it. This is a local acceptance runner, separate from hosted CI and deployment validation.

Documentation

• Full Documentation
• CLI Reference
• Azu Framework
• CQL ORM
• JoobQ

Contributing

1. Fork it (https://github.com/azutoolkit/azu_cli/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Elias J. Perez - creator and maintainer

Terminal diagnostics and generator validation

azu dev opens the workspace HUD (--ui rich and --ui mission select the same interface). Build, errors, console, configuration and commands share its navigation. Press g to compose a generator or : to enter an Azu command, review its arguments, then confirm execution without leaving the dashboard. See commands inside the HUD.

azu connect --ssh azu-production --snapshot /run/azu/monitor.json opens a read-only local HUD backed by verified SSH. Provision a restricted monitoring key and sanitized snapshot publisher first; the production connection guide covers setup, host-key verification, rotation and transport limits. Production mode has no generator, migration or console capability.

azu joobq provides queue, workflow-step and dead-letter views with bounded master/detail panes and confirmed atomic replay. azu dev adds an Errors tab and expands SQL with live queries, pool metrics and latency buckets. See JoobQ dashboard and dev telemetry requirements; expanded app telemetry requires the companion Azu producer changes, and PostgreSQL History Store support awaits a supported API.

Run scripts/check_generators.sh web and scripts/check_generators.sh api to compile every generator family together and exercise lazy-compiled message, job, validator and component paths. Release CI requires these checks, the generated-app end-to-end matrix, and scripts/check_joobq_adapter.sh against published JoobQ 0.4.2 and the pinned revision with atomic DLQ support.

Spark generators

Generate a typed live component or a complete live CRUD screen, styled with daisyUI:

azu generate spark Counter count:int32 --page
azu generate scaffold Product name:string price_cents:int32 active:bool --spark
azu db:setup
azu serve

The demo appears at /counters/live; /products provides paging, inline validation, editing and confirmed deletion, with updates between tabs and shared services for HTTP form fallbacks. Navigation and Spark wiring are registered automatically. See Spark generators for supported scalar fields, secret management, multi-process PubSub and authorization requirements. scripts/e2e_spark_app.sh generates and tests a disposable app in real Chromium.