CLI reference
Global behavior: openloop -V/--version prints the version; --help works on every command. Commands are strict (demandCommand); running a group without a subcommand prints help. Output defaults to tables in a TTY, JSON when piped; most list commands take --format table|json to override. Running bare openloop in a TTY launches the TUI.
project
Section titled “project”Manage linked repositories. See Projects.
| Command | Flags | Effect |
|---|---|---|
project add <alias> <path> |
--init, --force |
Register a repo; --init materializes templates, --force updates the path of an existing alias |
project list |
--format |
Table of alias / initialized / path |
project activate <alias> |
Set daemon’s preferred project | |
project show <alias> |
Print registry entry (JSON) | |
project init <alias> |
--force |
Materialize control plane; --force backs up .openloop/ to .openloop/backup/<timestamp>/ first |
project remove <alias> |
Unlink only; repo files preserved |
Manage the task ledger. See Tasks.
| Command | Flags | Effect |
|---|---|---|
task add |
-p <alias> (required), --title <t> or --from-ref <ref>, --kind <k>, --risk <r>, --scope <path…>, --depends-on <id…> |
Add a proposed task (default kind feature, risk medium-risk, promotion pull-request) |
task list |
-p, --status, --risk, --format |
Filtered ledger view |
task show |
-p, --task <id> |
Full task detail (JSON) |
task update |
-p, --task, --title, --status, --risk, --kind |
Patch a task |
task remove |
-p, --task |
Delete from ledger |
task recover |
-p |
Reset in_progress → ready |
task approve |
-p, --task |
awaiting-approval → ready |
Kinds: feature bugfix test refactor docs lint-fix type-fix localized-test-fix ci-heal discovery scope-proposal.
Risks: low-risk medium-risk high-risk.
Statuses: proposed planned ready awaiting-approval in_progress blocked done failed cancelled promoted.
approval
Section titled “approval”Human-review packets for pending work.
| Command | Flags | Effect |
|---|---|---|
approval list |
-p, --format |
Packets: risk, attempts, cost, branch |
approval show |
-p, --task |
One packet in full |
promotion
Section titled “promotion”Inspect or resolve promotions. See the promotion pipeline.
| Command | Flags | Effect |
|---|---|---|
promotion list |
-p, --task, --status pending|applied|rejected, --format |
Promotion artifacts |
promotion show |
-p, --task |
Artifact detail (decision, action, checks) |
promotion history |
-p, --task |
Full decision history |
promotion apply |
-p, --task, --note, --dry-run |
Apply a pending promotion locally (--dry-run previews) |
promotion reject |
-p, --task, --note |
Reject with a note |
promotion refresh |
-p, --task |
Pull live PR state via gh pr view (needs gh) |
service
Section titled “service”Manage the daemon. service run stays in the foreground for process managers.
| Command | Effect |
|---|---|
service start |
Spawn the detached daemon (refuses on foreign/stale PIDs; clears stale ones) |
service stop |
SIGTERM the daemon |
service status |
Print daemon-state.json |
service restart |
Stop + start |
service pause / service resume |
Toggle scheduling without killing the process |
service run |
Run the worker loop in the foreground (Ctrl+C to stop) |
run / run-once / enqueue
Section titled “run / run-once / enqueue”| Command | Flags | Effect |
|---|---|---|
run |
-p, --prompt (required), --model, --verbose |
Run Pi directly with a raw prompt (bypasses scheduler and provider config) |
run-once |
-p, --model, --verbose, --dry-run |
One full scheduler iteration; --dry-run prints selected task + prompt as JSON without invoking the agent |
enqueue |
-p, --ref |
Deprecated; use task add --from-ref |
status / watch / events / logs / report / digest / doctor
Section titled “status / watch / events / logs / report / digest / doctor”| Command | Flags | Effect |
|---|---|---|
status |
--format |
Per-project queue counts + daemon/budget state |
watch |
Live 1s-refreshing terminal dashboard (requires a TTY) | |
events |
-p, --since 30m|2h|1d (default 1h), --limit (default 50), --json |
Query the append-only audit log |
logs |
-p, --lines (default 50) |
Daemon log tail; with -p, recent run summaries from .openloop/runs/ |
report |
--hours (default 24), --format |
Human-readable activity summary |
digest |
--since-hours (default 24), --format |
Fleet digest: activity, spend split (measured/estimated), review queue with confidence |
doctor |
--format |
Check prerequisites, providers, daemon health |
GitHub/GitLab sync. See the issue sync guide.
| Command | Flags | Effect |
|---|---|---|
issue set-source |
-p, --github owner/name or --gitlab group/name, --label (default openloop), --token, --auto-sync, --post-comments (default on) |
Configure a project’s issue source |
issue sync |
-p, --token |
Import labeled issues as tasks |
issue list |
-p, --format |
Synced issues and their task ids |
issue remove-source |
-p |
Drop the source config |
config
Section titled “config”Global and project configuration. See the configuration guide and reference.
| Command | Effect |
|---|---|
config show |
Print global config |
config set <key> <value> |
Set a settable global key (dot notation; numbers validated) |
config set-model <model> |
Global default model |
config set-provider <pi|claude|aider|codex|opencode> |
Global default provider |
config list-providers |
Provider availability (✅/❌) |
config project-show <alias> |
Print project config |
config project-set-model <alias> <model> |
Project model |
config project-set-agent <alias> <provider> [--command <cmd>] |
Project provider (--command required for custom) |
config add-hook / remove-hook <index> / list-hooks |
Global lifecycle hooks (see hooks) |
config project-add-hook <alias> / project-remove-hook <alias> <index> / project-list-hooks <alias> |
Project hooks |
config add-channel / remove-channel <index> / list-channels |
Notification channels (webhook / desktop) |
Settable config set keys: budgets.dailyCostUsd, budgets.estimatedCostPerRunUsd, runtime.runTimeoutSeconds, runtime.maxAttemptsPerTask, runtime.noProgressRepeatLimit, runtime.tickIntervalSeconds, runtime.projectSelectionStrategy, notifications.onTaskComplete, notifications.onTaskFailed, notifications.onBudgetBlocked, notifications.onAllTasksDone.
dashboard
Section titled “dashboard”| Command | Flags | Effect |
|---|---|---|
dashboard start |
--port (default 7399) |
Run the web dashboard in the foreground |
dashboard enable |
--port |
Auto-start the dashboard with the daemon |
dashboard disable |
Disable auto-start | |
dashboard status |
Print dashboard config |
See the dashboard guide.
openloop mcp, stdio JSON-RPC 2.0 MCP server. See the MCP guide.
openloop setup, interactive wizard: prerequisites → link a project → stack detection → init, then offers to start the daemon.
Global flags
Section titled “Global flags”| Flag | Effect |
|---|---|
-V, --version |
Print version |
--help |
Help for any (sub)command |