CLI usage
PIPELINE is optional: with no arguments at all, agentic-dev-loop prints
the help. Flags without a positional use agentic-dev-loop/pipeline.yaml
(relative to the current directory); a missing default fails loudly instead
of falling back.
Exit code is 0 on pipeline success, 1 otherwise.
Run flags
| Flag | Effect |
|---|---|
--dry-run |
Full load-and-validate pass, then print the resolved plan. No LLM, no Docker, no state writes, no API key. Exit 0 on a clean load. |
--resume <thread-id> |
Continue the latest checkpoint of a previous run (crash, Ctrl-C, exhaustion) with all accumulated notes intact. |
--max-attempts <n> |
Override the pipeline's max_attempts. |
--env <file> |
Load secrets from a host env file outside the workspace. Optional: the process environment is the default, a named-but-missing file is a loud error, and values already set in the environment win. |
--no-viz / --viz-port <port> |
Suppress the live graph view / set a preferred port (default 8321; falls back to a free port when busy). |
Other commands
agentic-dev-loop run-status <pipeline>renders the latest run as a mermaid flowchart with the current step highlighted, reading the run-state checkpoint database directly.run-status --installinstalls the bundled/run-statuscommand into OpenCode.agentic-dev-loop reportserves the historical runs view in the browser (default port 8321, falling back to a free port when busy; blocks until ctrl+c and prints the URL). It reads the same run records as the markdown report and lists past runs with since / until / status filters, an aggregate metrics panel, and a per-run detail page carrying the brief, implementation summary, review findings, and QA report. The live viz also links to it from the History button in the graph page header.agentic-dev-loop report --markdown [<run-id>]renders the same history as ASCII markdown instead: an aggregate dashboard (loop health, TDD, review, and QA metrics with provenance labels) or a deep dive for one 12-hex run directory.--since/--until/--statusfilter the set.--markdowncannot be combined with--port.agentic-dev-loop containersinspects the engine's sandbox containers and networks from the host;containers --reapremoves registry-owned orphans whose owner process is dead. A SIGTERM to a running pipeline still closes the sandbox; SIGKILLed runs are reclaimed by the startup reaper on the next run or bycontainers --reap.agentic-dev-loop claude-loginauthenticates a Claude Pro or Max subscription (OAuth PKCE flow) and writes the token file the engine reads.agentic-dev-loop copilot-loginauthenticates a GitHub Copilot subscription (device flow);copilot-modelslists the models the token's tier can use. See LLM providers.
Onboarding commands
agentic-dev-loop init scaffolds the onboarding surface for a repo, and
doctor + upgrade keep the host and the committed pin honest. They are
your commands to run: the CLI never runs them for you.
agentic-dev-loop init --profile python # or: --profile dotnet-node, rust
agentic-dev-loop init --profile ./my-profile.yaml
agentic-dev-loop init --profile ./my-profile.yaml --recipe ./my-recipe.yaml
init writes the onboarding surface from a bundled toolchain profile:
agentic-dev-loop/pipeline.yaml, the three agent files,
agentic-dev-loop/.engine-version (the exact installed engine version), any
missing premise files, gitignore additions, and an env-file template. It
detects solution files, package.json directories, lockfiles, README, and
AGENTS.md, asks only what detection cannot answer, and refuses to overwrite
an existing agentic-dev-loop/ directory. A consumer-authored profile file
can be passed by path instead of a bundled name, and --recipe accepts a
consumer recipe file path the same way, so a toolchain this engine does not
ship can onboard with its own image and its own steps. A path profile is
stored in the pipeline relative to agentic-dev-loop/, so the committed
pipeline resolves from any working directory.
agentic-dev-loop doctor --fast # per-run gate: hard failures abort
agentic-dev-loop doctor --json # machine-readable results
doctor --fast probes the host and repo before you run: hard failures stop
you here (engine pin mismatch, engine runtime availability, API version, git
repo, .env* files); warnings print and continue.
upgrade installs the latest engine release and rewrites the pin, so the
host install and the committed pin converge in one explicit action.
See Authoring a loop for what init writes and how to adapt
it.