Cli

+++ title = "CLI reference" description = "Every flag and subcommand for the loco app generator and the cargo loco runtime CLI." date = 2021-05-01T18:10:00+00:00 updated = 2021-05-01T18:10:00+00:00 draft = false weight = 2 sort_by = "weight" template = "docs/page.html" aliases = ["/docs/getting-started/starters/"]

[extra] lead = "" toc = true top = false +++

Loco ships two command-line surfaces:

cargo loco has two main() implementations, selected by the with-db Cargo feature (src/cli.rs:712 when with-db is on, src/cli.rs:872 when it is off). The non-with-db build has no Db subcommand and no DB-backed generators (model/migration/scaffold). Both variants share the same top-level -e, --environment <ENV> global flag (default development).

1. loco new — the app generator

Source: loco-new/src/bin/main.rs:30-62.

1.1 Global flag

1.2 new flags

There is no -t/--template and no -v/--verbose flag. The Template enum exists internally and derives ValueEnum, but it is not wired to any CLI argument — template choice is interactive-only (§1.4).

If --db, --bg, and --assets are all supplied, the wizard skips every prompt except app name (wizard.rs:287-297); app name still prompts unless --name is also given.

1.3 Interactive prompts (when flags are omitted)

Source: loco-new/src/wizard.rs.

1. App name? (default myapp) — non-empty, no leading digit, Unicode XID + -/_ (wizard.rs:201-267).
2. "You are inside a git repository. Do you wish to continue?" — only if cwd is a git repo and --allow-in-git-repo was not passed; default No, aborts on decline (wizard.rs:227-240; main.rs:91-94).
3. "What would you like to build?" — template select (wizard.rs:299-302).
4. Conditional DB / background / assets follow-ups, depending on the chosen template.

1.4 Templates

Source: wizard.rs:12-27, branch logic wizard.rs:304-333.

1.5 Option enums (clap values + menu labels)

DBOption — wizard.rs:39-79 — clap --db values: sqlite (default), postgres, none.

BackgroundOption — wizard.rs:81-125 — clap --bg values: async (default), queue-redis, queue-postgres, queue-sqlite, blocking.

AssetsOption — wizard.rs:127-162 — clap --assets values: serverside (default), clientside, none.

OS — loco-new/src/lib.rs:41-51 — clap --os values: windows, linux, macos. windows adds a second tool bin target to the generated Cargo.toml (Cargo.toml.t:65-70).

1.6 Derived generation settings

Source: loco-new/src/settings.rs:58-89.

• DB enabled → Features::default() (loco-rs default features apply to the generated app).
• DB disabled (Lightweight template, or --db none) → default-features = false, feature names = ["cli"]; if background is queue-redis, "worker_redis" is appended; if background is queue-postgres or queue-sqlite, "worker" is appended.
• auth and mailer scaffolding are enabled iff DB is enabled.
• Serverside assets → generated Initializers { view_engine: true }.
• loco_version_text: normally version = "0.17"; when env var LOCO_DEV_MODE_PATH is set, becomes version = "*", path = "<that path>" — this is how the local framework checkout is dogfooded.
• Generated app's own edition is pinned in loco-new/base_template/Cargo.toml.t independent of the loco-rs framework edition.

2. cargo loco — the runtime CLI

Source: src/cli.rs:64-171 (enum Commands).

2.1 Top-level subcommands

Start-mode resolution (cli.rs:736-750): --all or (--server-and-worker and --scheduler) → All; --server-and-worker alone → ServerAndWorker; --worker[=tags] (+ --scheduler) → WorkerAndScheduler / WorkerOnly; --scheduler alone → ServerAndScheduler; none of the above → ServerOnly.

2.2 db subcommands

enum DbCommands, src/cli.rs:483-523 — only present when with-db is enabled.

2.3 jobs subcommands

enum JobsCommands, src/cli.rs:598-647 — only present when the worker feature is enabled (worker_redis implies worker).

2.4 generate subcommands

enum ComponentArg, src/cli.rs:173-382 — only present in debug builds (#[cfg(debug_assertions)] on Commands::Generate). model/migration/scaffold are additionally gated on #[cfg(feature = "with-db")]. Full field-type syntax is covered in the Generators & field types reference; this table lists CLI shape only.

The -k/--kind flags and the ScaffoldKind enum were removed in 1.0. For back-compat, scaffold and controller still accept --api (a no-op) and --html/--htmx (which error with a pointer to the React SPA frontend), so pre-1.0 commands don't break.

3. cargo loco --help (verified output)

The top-level help, matching enum Commands exactly:

The one-person framework for Rust

Usage: demo_app-cli [OPTIONS] <COMMAND>

Commands:
  start       Start an app
  db          Perform DB operations
  routes      Describe all application endpoints
  middleware  Describe all application middlewares
  task        Run a custom task
  jobs        Managing jobs queue
  scheduler   Run the scheduler
  generate    code generation creates a set of files and code templates based on a predefined set of rules
  doctor      Validate and diagnose configurations
  version     Display the app version
  watch       Watch and restart the app
  help        Print this message or the help of the given subcommand(s)

Options:
  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
  -h, --help                       Print help
  -V, --version                    Print version