Quick Start

Installation

TODO

Go to the project repo and run

rake install

Initialization

Run loci init in your project root to initialize Loci and prepare the generator structure.

loci init

This creates the following layout:

.generators.yml        # Generators configuration
loci/
├─ generators/         # Main generators directory
├─ types/              # Custom input types
└─ shared/             # Shared utility classes

All directories under loci/ are automatically loaded via Zeitwerk, so no manual require statements are needed.

Adding Your First Generator

Create a new generator using the loci add command:

loci add backend:controller

This generates the following structure:

loci/
├─ generators/
│  └─ backend/
│     └─ controller/
│        ├─ templates/
│        ├─ controller_generator.rb
│        └─ README.md

Generators are grouped by their top-level namespace (backend in this example). Namespaces are optional:

loci add controller

Use --global (-g) to add the generator to the global directory at ~/.loci/ instead, making it available across all projects:

loci add backend:controller --global

Each generator has its own namespace, so you are free to split its logic across multiple files if needed. Related templates live in the templates/ directory.

The README.md file serves as the detailed generator's documentation. It is used by:

• The CLI help output loci g backend:controller --help
• AI agents

Running a Generator

Run the generator using the loci g command:

loci g backend:controller arg1 arg2 --flag --val foo

This invokes the generator and populates the params object with the parsed inputs. From there, your steps execute with validated, structured data.

Defining Steps

Every generator should define at least one step. Steps run in order, and can include forward/reverse behavior.

module Backend
  class ControllerGenerator < Loci::BaseGenerator
    arg :name, required: true

    step "Create controller file" do
      path = "app/controllers/#{params.name}_controller.rb"

      up   { create_file path, "class #{params.name}Controller\nend\n" }
      down { remove_file path }
    end
  end
end