Command Reference

caelix new

caelix new <name>

Pass --backend axum to generate an Axum-backed app. The default is Actix.

Creates a new Caelix application directory named <name>.

The command creates Cargo.toml, AGENTS.md, src/main.rs, src/lib.rs, and src/app.rs. The package name comes from the target directory and is converted to kebab case.

caelix doctor

caelix doctor

Runs cargo run -- --doctor in the current Cargo project. The normal application binary completes full startup validation, runtime route setup, and shutdown without binding a network socket. It returns a non-zero exit status when compilation, configuration, startup, or shutdown fails.

caelix generate module

caelix generate module <name>
caelix g module <name>

Creates a feature module, service, and controller below src/<normalized-name>/.

Generation requires a Cargo.toml in the current directory. It refuses to create files when run outside a Cargo project.

caelix generate service

caelix generate service <name>
caelix g service <name>

Creates service.rs and creates mod.rs only when missing.

Generation requires a Cargo.toml in the current directory.

caelix generate controller

caelix generate controller <name>
caelix g controller <name>

Creates controller.rs and creates mod.rs only when missing. A matching service is injected only when src/<feature>/service.rs already exists.

Generation requires a Cargo.toml in the current directory.

If the service does not exist, the controller is generated without a service dependency and the CLI prints a note.

Name Rules

Names are trimmed and cannot be empty or contain / or \. The normalized Rust module name cannot start with an ASCII digit.

Examples:

Invalid names include an empty string, names containing / or \, and names whose normalized Rust module name starts with an ASCII digit.

Overwrite Rules

The CLI refuses to overwrite files. Typical errors:

src/users/service.rs already exists; refusing to overwrite

Registration

Generation does not edit src/app.rs or src/lib.rs. Register generated modules manually:

#![allow(unused)]
fn main() {
pub mod users;
}

#![allow(unused)]
fn main() {
use crate::users::UsersModule;

impl Module for AppModule {
    fn register() -> ModuleMetadata {
        ModuleMetadata::new().import::<UsersModule>()
    }
}
}