Skip to content

Recipes and app scaffolding

Serenade reproduces the Flex recipe concept on top of Cargo. Cargo owns dependencies (Cargo.toml, cargo add, crates.io / git / path). The serenade CLI owns composition: skeleton trees and package config stubs.

CLI stack

Section titled “CLI stack”
Crate Role
clap Command tree and argument parsing
cling Handler dispatch on top of clap (no giant match)
clap_complete Shell completions (serenade completion <shell>)
clap_mangen Man page (serenade man [--output PATH])
ratatui Guided recipe picker (serenade tui)

clap stays the parser. cling structures implementation. Completions and man pages are generated from the same Command tree (CommandFactory + debug_assert in tests).

Commands

Section titled “Commands”

Build the CLI from this workspace:

Terminal window
make serenade ARGS='--help'
# or: make tui / make recipe-list

Prefer Make aliases (make/cli.mk) over cargo run -p serenade-cli --bin serenade -- ....

Command Role
serenade new <name> Create an app skeleton (config/packages/*.toml, .env.example, src/main.rs, src/bin/console.rs)
serenade recipe list List embedded recipes
serenade recipe apply <id> Copy recipe files into an app root; run cargo add for declared crates unless --no-cargo
serenade tui Guided ratatui picker: choose a recipe, Enter applies (same flags as recipe apply)
serenade completion <shell> Print shell completions
serenade man Print a man page (or --output PATH)

Flags:

  • new --path DIR --force
  • recipe apply --root DIR --force --no-cargo
  • tui --root DIR --force --no-cargo

Recipe format

Section titled “Recipe format”

Each recipe is a directory with recipe.toml plus optional files/:

id = "framework"
description = "Framework package config and registration hints"


[cargo]
dependencies = [
  { crate = "serenade-bundle", git = "https://github.com/Interchouette-ITC/Serenade.git", branch = "dev" },
]


[[files]]
src = "files/config/packages/framework.toml"
dest = "config/packages/framework.toml"


[hints]
bundles = ["FrameworkBundle"]
note = "Register FrameworkBundle and load FrameworkExtension."

Shipped recipes: admin, framework, security (config package scaffold; authenticator wiring is application-owned).

Package config

Section titled “Package config”

Default format is TOML under config/packages/. YAML remains loadable through serenade-config; recipes ship TOML. Environment overlays live in config/packages/{env}/ (for example config/packages/dev/). Scaffolded apps call load_dotenv then build_container(..., env, ...).

Console vs CLI

Section titled “Console vs CLI”
Surface Crate Role
Scaffolding serenade-cli (serenade binary) new / recipe / tui / completions / man
In-app console serenade-console bin/console analogue (serenade:about, debug:container, …)

Do not invent a second package manager. In-app console still uses clap (+ optional ratatui for interactive debug). Scaffolding uses clap + cling; serenade tui adds a recipe picker (ratatui) on the same CLI binary.