Loco CLI
Relevant source files
The following files were used as context for generating this wiki page:
Loco CLI is the primary command-line interface and "driving tool" for the Loco framework, designed to streamline the lifecycle of Rust-based web applications. It serves as a powerful code generator and operational utility that enables developers to build, manage, and scale applications with minimal manual configuration. By following the "Convention Over Configuration" principle, the CLI provides an intuitive wizard-based experience for scaffolding new projects and maintaining existing ones.
The CLI is split into two primary roles: the loco-cli (often installed as loco) used for bootstrapping new projects from templates, and the internal application CLI (accessed via cargo loco) used for project-specific operations such as database migrations, task execution, and server management.
Sources: README.md, loco-new/README.md, loco-cli/README.md
Core Functionalities
The Loco CLI provides a comprehensive suite of tools categorized into project initialization, code generation, and system diagnostics.
Project Initialization (loco new)
The loco new command initiates an interactive wizard that guides the user through selecting a starter template and configuring essential project components.
The diagram shows the interactive decision tree handled by the CLI during project creation.
| Component | Description |
|---|---|
| SaaS Starter | Includes user authentication (JWT), DB integration, and background processing. |
| REST API | Focused on robust API endpoints with database support and modular controllers. |
| Lightweight | Minimal setup with essential controllers and views for simple services. |
Sources: loco-new/README.md, loco-cli/README.md, snipdoc.yml:20-37
Development and Operations
Once a project is created, the CLI becomes the primary interface for daily development tasks.
- Database Management: Commands for resetting the database (
db reset), running migrations (db down), and generating entities from the schema (db entities). - Scaffolding: Rapidly generate code for models, controllers, and views using
generate scaffold. - System Diagnostics: The
doctorcommand validates the development environment, checking SeaORM CLI installation, Database connectivity, and Redis status.
Sources: DEVELOPMENT.md:27-38, snipdoc.yml:108-115, snipdoc.yml:122-125
Template Generation Engine
The CLI's generation logic is driven by a starters folder where each template contains a generator.yaml file. This engine uses regex patterns and block markers to customize the generated code based on user input.
Generator Logic
The generator.yaml defines rules for:
- Global Replacements: Replacing placeholder strings (e.g.,
loco_starter_template) with the user's chosen application name. - Conditional Blocks: Enabling or disabling code sections using markers like
(block-name-start). This is used to toggle features like specific database providers or background worker types.
This diagram illustrates how the CLI processes the generator configuration to transform a template into a customized project.
Sources: loco-cli/README.md:25-72
Common Commands Reference
The following table summarizes the most frequently used CLI commands as defined in the project documentation and configuration.
| Command | Purpose | File Reference |
|---|---|---|
loco new | Create a new project via interactive wizard. | loco-cli/README.md:14 |
cargo loco start | Launch the web server. | snipdoc.yml:84 |
cargo loco doctor | Validate DB, Redis, and CLI dependencies. | snipdoc.yml:108 |
cargo loco db reset | Drop and recreate the database structure. | DEVELOPMENT.md:29 |
cargo loco db entities | Generate SeaORM entities from the DB. | DEVELOPMENT.md:36 |
cargo loco generate scaffold <NAME> | Generate Model, Controller, View, and Migrations. | snipdoc.yml:122 |
cargo loco task <TASK> | Execute a custom defined background task. | snipdoc.yml:132 |
Sources: snipdoc.yml, DEVELOPMENT.md
Testing and Maintenance
The Loco CLI includes specific workflows for maintainers to ensure reliability across updates.
Snapshot Testing
The project uses insta for snapshot testing to detect changes in CLI output and behavior. CLI-specific snapshots are updated using the LOCO_CI_MODE=true TRYCMD=overwrite cargo test command.
Sources: CONTRIBUTING.md:104-118
Local Development
To test the CLI against a local version of the framework instead of fetching templates from GitHub, developers can use the STARTERS_LOCAL_PATH environment variable.
STARTERS_LOCAL_PATH=[PATH]/loco cargo run new --path /tmp
Sources: loco-cli/README.md:20-23
Loco CLI acts as the cohesive link between the framework's conventions and the developer's productivity. By automating repetitive scaffolding and providing robust diagnostic tools, it enables a "one-person" development team to manage complex Rust web applications efficiently.