Seed sonny’s config/data/cache directories on this host with a starter
models.yaml. Idempotent — running it twice is harmless.
Usage:
sonny init [flags]
sonny init [command]
What it creates
Directories:
| Path | Contents |
|---|---|
| config dir | models.yaml, pack-sources.yaml |
config dir/models.d | drop-in model catalog fragments |
data dir/packs | user recipe YAMLs go here |
| cache dir | git-backed recipe clones |
Files (only if missing): models.yaml (embedded example, edit to taste).
Pass --system to use the system layout (/usr/local/share/sonny/...) in
package post-install scripts. Pass --force to overwrite an existing
models.yaml.
Flags
| Flag | Type | Description |
|---|---|---|
--default-model | string | optionally select a default model as source/model when none is saved |
--default-recipe | string | optionally select a default recipe when none is saved |
--force | — | overwrite existing files (models.yaml) |
-h, --help | — | help for init |
--system | — | use system data dir (for packagers / post-install scripts) |
All init subcommands accept the global flags
.
init defaults
Select optional startup defaults. Existing choices are preserved. Skip either
flag to keep automatic task routing. List choices with
sonny recipe list --recipes and sonny models list.
Usage:
sonny init defaults [flags]
| Flag | Type | Description |
|---|---|---|
--default-model | string | optionally select a default model as source/model when none is saved |
--default-recipe | string | optionally select a default recipe when none is saved |
-h, --help | — | help for defaults |
init project
Harvest this directory’s agent-instruction files (AGENTS.md, CLAUDE.md,
.claude/ commands/skills/agents, Cursor/Windsurf/Copilot files) into a
generated recipe suite under .sonny/packs/.
The suite’s primary recipe inherits (parent:) from the nearest ancestor
directory that has also run sonny init project, so instructions compose down
the directory hierarchy. A drift manifest (.sonny/init-manifest.yaml) records
source hashes; sonny run refreshes the harvested sections automatically when
sources change.
By default the configured provider (--provider/--model, .sonny.yaml, or
SONNY_PROVIDER/SONNY_MODEL) writes a synthesized main prompt; pass --no-llm
(or configure no provider) for a deterministic template. Reruns never overwrite a
hand-edited generated file: it is kept and reported as a conflict.
Usage:
sonny init project [flags]
sonny init project [command]
| Flag | Type | Description |
|---|---|---|
--force | — | replace hand-edited generated files (explicit destructive choice) |
-h, --help | — | help for project |
--json | — | print the result as one JSON document |
--mcp | — | harvest MCP server configs into .sonny/mcp.yaml (remembered; --mcp=false disables) |
--no-llm | — | skip LLM synthesis; use the deterministic template |
Subcommands drive the same init service step by step and never prompt:
| Subcommand | Purpose |
|---|---|
abandon | Abandon an unfinished init operation |
apply | Apply a reviewed init plan by id (never prompts) |
campaigns | List evaluation, optimization, promotion and rollback receipts |
canary | Explicit Canary actions: legacy migration and the evidence session |
dataset | Build and list the project’s history datasets |
eval | Evaluate the project’s recipe against its imported history dataset |
history | Import this project’s attributable agent history (Sonny, Claude, Codex) |
index | Publish the project’s local source index |
optimize | Optimize the project’s recipe against its history dataset (staged, never activated) |
plan | Show what an init apply would do, without writing anything |
promote | Activate an improved optimization candidate by receipt |
rebind | Bind the project’s private init state to this checkout |
repair | Regenerate missing or stale init outputs, keeping hand-edited files |
resume | Resume an unfinished init operation |
rollback | Re-activate a recorded generation of the project’s recipes |
setup | Provision local isolation and a protected analysis deployment |
status | Show the project’s init state and per-subsystem readiness |
init project setup
Provision a per-user rootless Docker engine (or use the system Docker engine
when it runs with userns-remap), verify a signed Sonny isolation image, and
grant this project’s enabled analysis pipeline access to its workspace and
configured model providers. Existing operator configuration is preserved.
Usage:
sonny init project setup [flags]
| Flag | Type | Description |
|---|---|---|
--dir | string | project directory (default: current directory) |
-h, --help | — | help for setup |
--host-local | — | grant analysis without an isolation realm (selected automatically when no usable isolation Docker engine exists) |