modo-cli

CLI tool for scaffolding new modo framework projects.

Installation

cargo install modo-cli

After installation the modo binary is available on your $PATH.

Usage

Create a new project

modo new <NAME> [OPTIONS]

--postgres and --sqlite are mutually exclusive.

Templates

Examples

Create a minimal project (no database):

modo new my-service --template minimal

Create a JSON API project backed by SQLite (default):

modo new my-api --template api

Create a JSON API project backed by PostgreSQL:

modo new my-api --template api --postgres

Create a full-stack web app (default template, SQLite):

modo new my-app

Web app with PostgreSQL and S3 storage:

modo new my-app --postgres --s3

After scaffolding

The CLI prints the recommended next steps. For a web project:

cd my-app
just assets-download     # download HTMX, Alpine.js, Tailwind Elements (first time only)
just dev                 # start Docker services, build CSS, run dev server

For other templates (api, worker, minimal):

cd my-service
just dev

When Docker Compose services are configured (Postgres via --postgres, RustFS via --s3, or Mailpit in web templates), just dev starts them automatically.

Project name rules

• Must start with an ASCII letter or underscore ([a-zA-Z_])
• May contain [a-zA-Z0-9_-]
• Must not be a Rust keyword

What gets generated

Every project receives shared files plus template-specific files. Shared files applied to all templates:

• .gitignore
• CLAUDE.md — AI coding instructions for the project

Template-specific files (vary by template):

• Cargo.toml — pre-configured with the selected modo crates
• src/main.rs — application entry point
• src/config.rs — typed configuration struct
• config/development.yaml and config/production.yaml
• .env and .env.example
• justfile — development task runner

The api and web templates also generate src/handlers/ and src/models/. The web template additionally generates src/views/, src/tasks/, assets/, templates/, and locales/. The worker template generates src/tasks/.

The web and worker templates create a data/ directory (with a .gitkeep) as the default SQLite database location.

A docker-compose.yaml is generated when it has content to include:

• web template: always generated (always includes Mailpit for email); adds Postgres when --postgres; adds RustFS when --s3
• api and worker templates: only generated when --postgres is passed (Postgres service only)
• minimal template: never generated

A git init is run automatically in the new directory after scaffolding.

Template variables

Templates are rendered with MiniJinja. The scaffold-time variables available in .jinja files are:

Email templates under templates/emails/ use {% raw %}...{% endraw %} blocks to preserve runtime Jinja variables (such as {{name}} and {{subject}}) so they are not consumed during scaffolding.