CLI reference¶

mini-ork is a single dispatcher. Every capability is a subcommand registered on mini_ork.cli.main.SUBCOMMAND_REGISTRY, so the surface is stable even as new commands are added. This section documents each command, its flags and its exit codes.

mini-ork --help          # the full command map
mini-ork <command> --help

How the CLI is organised¶

Group	Commands	What it is for
Recipe runner	`run`	The main entry: classify → plan → execute → verify
Universal loop	`classify` `plan` `execute` `verify` `reflect` `improve` `eval` `promote`	Drive one stage yourself, or drive the learning loop
Verification	`certify`, `verifier`	Judge a change against its claim; label verifier outcomes
Learning	`lessons`, `apply`	Inspect learned rules; close the apply loop
Self-improvement	`self-improve`	Rewrite this checkout under verifiers
Inspection	`board`, `version`, `mcp-context`	Read project state as JSON or text
Credentials	`providers`, `vault`	Configure lanes; inspect the secret backend chain
MCP servers	`mcp`	Register servers that nodes grant by name
Coordination	`concord`	Principals, mailboxes, scope claims
Scheduling	`automations`	Run recipes on a schedule
ContextNest	`cn`	Query the cross-session memory service
IDE	`zed`	Wire mini-ork into Zed's settings
Maintenance	`init` `install` `update` `doctor` `validate` `garden`	Bootstrap, repair, check

Global environment¶

These variables are read before any subcommand runs:

Variable	Default	Effect
`MINI_ORK_HOME`	`<cwd>/.mini-ork`	Project home: config, runs, state
`MINI_ORK_DB`	`$MINI_ORK_HOME/state.db`	SQLite state database
`MINI_ORK_ROOT`	engine checkout	Which engine is running
`MINI_ORK_PROVIDERS`	`$MINI_ORK_HOME/config/providers.yaml`	Provider registry override
`MINI_ORK_AGENTS`	`config/agents.local.yaml`	Personal lane overlay
`MINI_ORK_DRY_RUN`	unset	`1` makes subcommands dry-run by default
`MINI_ORK_RUN_ID`	generated	Re-bind a process to an existing run
`MINI_ORK_RUN_DIR`	derived	The run's artifact directory

The complete contract is in Environment variables.

Exit codes¶

Commands that gate CI follow sysexits conventions:

Code	Meaning	Used by
`0`	Success / verdict passed	all
`1`	Command failed / verdict refuted	`certify`, `run`
`2`	Usage error, or verdict unverified	`certify`, most commands
`64`	Usage error with a clear diagnostic (`EX_USAGE`)	`certify`, `run --resume`
`65`	Recorded state is unreadable (`EX_DATAERR`)	`run --resume`
`70`	Unexpected internal failure (`EX_SOFTWARE`)	`run --resume`

run --resume uses the narrow set 0/2/64/65/70 so a wrapper can distinguish "you typed the run id wrong" from "the checkpoint ledger is corrupt".

Common invocations¶

# One run, recipe chosen by the classifier
mini-ork run ./kickoff.md

# Force a recipe
mini-ork run code-fix ./kickoff.md

# Stop after planning, inspect the plan
mini-ork plan ./kickoff.md --dry-run

# Judge a diff against its claim
mini-ork certify --base main~1 --head HEAD --issue "median() returns wrong value"

# Project state as JSON (what the IDE reads)
mini-ork board

# Diagnose the environment
mini-ork doctor && mini-ork validate

Adding a subcommand¶

Every command is registered on mini_ork.cli.main.SUBCOMMAND_REGISTRY with the signature handler(rest: list[str], root: str) -> int, where the return value is the process exit code:

from mini_ork.cli.main import register_subcommand

def my_command(rest, root):
    print("hello from", root)
    return 0

register_subcommand("my-command", my_command)

register_subcommand replaces an existing entry with the same name. The dispatcher itself never needs editing — see Extending mini-ork.