Arguments

Arguments define the input schema of a generator.

All parsed inputs are available through the params object inside the generator’s call method. Inputs are normalized and validated before execution begins.

Arguments are divided into two categories: positional arguments and options.

Positional Arguments

Positional arguments are matched by order.

Single Argument

A single positional argument consumes exactly one CLI value.

arg :name

loci g example John

params.name
# => "John"

Variadic Arguments

Variadic arguments capture all remaining positional values.

arg :name
args :files

loci g example John a.txt b.txt c.txt

params.files
# => ["a.txt", "b.txt", "c.txt"]

• Only one variadic argument is allowed per generator
• It may be defined in any place, but it always process the tail of argument list.

Options

Options are named inputs passed via flags. They are order-independent.

---

Boolean Flags

CLI options provided without an explicit value are treated as true. Set the option's default value to false to enable toggle-style flag behavior.

option :verbose, default: false

loci g example --verbose

params.verbose
# => true

If the flag is not provided:

params.verbose
# => false

---

Single-Value Option

option :name

loci g example --name "Jane Doe"

params.name
# => "Jane Doe"

---

Array Option

Array options accept repeated values.

option :tags, array: true

loci g example --tags ruby --tags git
# or
loci g example --tags=ruby,git

params.tags
# => ["ruby", "git"]

Each value is processed independently.

---

Hash / Map Option

Options with a hash default accept key–value pairs.

option :meta, default: {}

loci g example --meta author:alice version:1.0

params.meta
# => { "author" => "alice", "version" => "1.0" }

They can also process nested keys using dot notation, which automatically builds nested structures within the resulting hash.

option :meta, default: {}

loci g example --meta author:alice user.name:bob user.address.city:london

params.meta
# => {
#      "author" => "alice",
#      "user" => {
#        "name" => "bob",
#        "address" => {
#          "city" => "london"
#        }
#      }
#    }

If a key is provided with comma-separated values, it is automatically converted into an array.

loci g example --meta author:alice tags:tag1,tag2,tag3

params.meta
# => {
#      "author" => "alice",
#      "tags" => ["tag1", "tag2", "tag3"]
#    }

You can also use array: true with map options. This allows you to pass the same option multiple times to generate a list of nested objects.

option :users, array: true, default: {}

loci g example --users name:alice city:london --users name:bob city:paris

params.users
# => [
#      { "name" => "alice", "city" => "london" },
#      { "name" => "bob", "city" => "paris" }
#    ]

Input Parameters

Both positional arguments and options support the following parameters.

---

required

Marks the argument as mandatory.

option :address, required: true

If omitted at the CLI, validation fails and execution does not start.

---

default

Provides a fallback value when no input is given.

option :environment, default: "dev"

loci g example

params.environment
# => "dev"

---

array

Enables repeated input values.

option :ids, array: true

params.ids
# => ["1", "2", "3"]

Variadic positional arguments behave the same way by default.

---

type

Casts values after parsing.

arg :start_date, type: Date

loci g example 2025-01-01

params.start_date
# => #<Date: 2025-01-01>

params.start_date.class
# => Date

Casting happens automatically before execution.

---

description

option :force, description: "Overwrite existing files"

Descriptions appear in:

• CLI help output
• AI agent metadata

---

Transformation Block

A transformation block allows you to normalize values immediately after parsing.

option :shout do |value|
  value.to_s.upcase
end

loci g example --shout hello

params.shout
# => "HELLO"

If type is also specified, the transformation runs before type casting.

For array inputs, the block runs once per element.