Maintenance commands¶

Project setup, upgrades and static checks. These commands are cheap and safe to run often; each prints a Fix: hint on every finding rather than dumping a raw error.

Command	Purpose
`init`	Scaffold `.mini-ork/` and seed config
`install`	Install a user-level launcher
`update`	Apply pending DB migrations and report config drift
`doctor`	Report tools, engine, credentials, vault
`validate`	Pre-run static checks on a kickoff or recipe
`garden`	Project drift detection
`recipe-eval`	Static evaluation of recipe definitions
`sandbox-gc`	Reap leaked sandbox instances
`version`	Print the engine version

init¶

mini-ork init

Creates the project home — kickoffs/, INBOX/, runs/, locks/, secrets/, config/ — seeds the task classes and agents.yaml, initialises state.db, and appends the generated-state block to .gitignore. It is idempotent: existing files are reported as already present and never overwritten, so it is safe to re-run after an upgrade to pick up new seeds.

A committed .mini-ork/engine pointer records which engine the project uses. init seeds it; do not delete it.

install¶

mini-ork install [--bin-dir <path>] [--no-path] [--force] [--dry-run]

Installs a user-level launcher — ~/.local/bin on macOS, Linux and WSL, %LOCALAPPDATA%\mini-ork\bin on Windows. --no-path skips the shell-profile edit, --force replaces a non-mini-ork file at the target, and --dry-run prints the plan. This is distinct from the one-line installer in Installation, which fetches the engine.

update¶

mini-ork update [--dry-run] [--pull]

Applies pending migrations to the project's state.db and reports drift between the shipped config templates and your local .mini-ork/config. Local config is never silently overwritten — drift is reported so you can merge it. --dry-run lists pending migrations without writing. --pull runs git pull --ff-only in MINI_ORK_ROOT first; it refuses a diverged checkout rather than creating a merge commit inside an engine directory.

Engine and home must agree

doctor warns when the home was last migrated by a different engine version than the one running. Run update from the engine you intend to keep using; do not mix two engine checkouts against one home.

doctor¶

mini-ork doctor

Reports, in order:

required tools: sqlite3, git, curl, claude, codex, python3;
MINI_ORK_HOME / MINI_ORK_DB resolution;
the engine root, version and commit, plus the home's migrated version;
provider preflight: Anthropic and Codex CLI presence, and whether the GLM_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY and DEEPSEEK_API_KEY families resolve;
vault backends and the protection gap.

Run it first whenever a run fails before dispatching anything.

validate¶

mini-ork validate [kickoff.md] [--recipe <name>] [--strict]

Pre-run static checks. With a kickoff it infers the recipe; --recipe forces one. It catches missing sections, contradictory scope, absent acceptance criteria and a recipe whose contract cannot bind. --strict treats warnings as errors — use it in CI for kickoff templates.

garden¶

mini-ork garden [--strict]

Drift detection over the project: stale engine pointers, orphaned run directories, config files that no longer match the schema, recipe pins that no longer resolve. It repairs nothing; every finding carries a Fix: hint. --strict exits nonzero on warnings too, which makes it a useful scheduled job.

recipe-eval¶

mini-ork recipe-eval [recipe-name] [--json]

Static evaluation of recipe definitions — missing files, unresolvable node references, artifact contracts with ports no node produces, gates no evaluator registers. Run it after adding or editing a recipe and before dispatching a real run. --json is the CI form.

sandbox-gc¶

mini-ork sandbox-gc [--backend <name|all>] [--max-age SECONDS] [--dry-run]

Reaps leaked sandbox instances older than a TTL. --backend defaults to all, which covers every registered reaper and node provider; --max-age defaults to MO_SANDBOX_MAX_AGE, then a built-in default. --dry-run reports what would be reaped and removes nothing. Use --dry-run first after a crashed run.

version¶

mini-ork version

Prints the engine version. For the commit and the home's migrated version, use doctor.

A safe maintenance sequence¶

mini-ork doctor            # know the state before changing it
mini-ork update --dry-run  # see pending migrations
mini-ork update            # apply them
mini-ork validate          # re-check the recipe surface
mini-ork garden --strict   # catch drift introduced by the upgrade

Exit codes¶

Command	Nonzero when
`validate`, `garden`, `recipe-eval`	A finding is an error — or a warning under `--strict`
`doctor`	A required tool is missing
`update`	A migration failed, or `--pull` could not fast-forward
`sandbox-gc`	A backend's reaper raised