CLI reference

Run devflow --help-all for the authoritative surface straight from your binary. Automation should prefer --json --non-interactive (contract).

Global flags

devflow [--json] [--non-interactive] [-s <service-name>] <command>

Flag	Description
--json	structured JSON on stdout where supported
--non-interactive	no prompts; unapproved hooks are skipped with a warning; destructive ops require --force
-s <name>	target a specific configured service (defaults to the default: true service)

Daily workspace flow

devflow switch [workspace]

Create or switch a workspace, align services, move into the worktree, run hooks. No argument = interactive fuzzy picker.

devflow switch
devflow switch feature/auth
devflow switch -c feature/new --from develop
devflow switch feature/auth -x "npm run dev" --detach
devflow switch feature/auth --dry-run

Flag	Effect
-c, --create	create the workspace first
-b, --from <ws> (alias --base)	parent workspace for creation (default: current context)
-x, --execute <cmd>	run a command after switching (in the worktree); trailing args after --
-d, --detach	run the -x command in a detached tmux/zellij session
-o, --open	open an interactive multiplexer session in the workspace
--no-services	VCS only — skip service branching
--no-processes	skip process auto-start during switch
--no-verify	skip all hooks
--template	select the configured default workspace and its services
--dry-run	print the plan (worktree path, services, hooks) without acting
--no-respect-gitignore	also copy gitignored entries into a newly created worktree (one-shot copy_ignored: true)

In JSON mode, switch emits exactly one document with raw workspace, backend service_key, and worktree_path. When -x, --detach, or --open is used, it adds a nested execution result (including captured stdout/stderr when present) instead of printing a second document.

devflow list · devflow status

devflow list            # parent tree: paths, services, processes, and health
devflow --json list     # versioned tree document with a stable shape
devflow status          # current workspace, services, connections

The list document contains schema_version, project/VCS metadata, context_workspace, default_workspace, roots, workspace nodes, flat_order (canonical depth-first display order with per-row depth/connector data), and warnings. Nodes expose raw name, effective service_key, newly-derived canonical_service_key, identity_status, immutable parent, children, worktree_path, health, services, processes, created_at, executed_command, and execution_status. New keys are collision-safe; an unambiguously migrated workspace may retain its legacy key for data continuity. The shape is the same with zero, one, or many services.

devflow connection <workspace>

Alias for service connection. --format uri|env|json.

devflow link <workspace>

Adopt an existing materialized VCS workspace into devflow (registry entry + optional service provisioning). --from <ws> records its creation parent.

devflow remove <workspace>

Delete a workspace, its worktree/VCS ref, and services. A read-only preflight protects dirty/default/current workspaces. Removal hooks run while the directory exists, followed by processes and services; the worktree/ref and registry entry are removed last. A service failure leaves code intact for retry. --force accepts dirty/partial-cleanup risk and is required in --json/--non-interactive; --keep-services removes only the worktree/ref.

devflow cleanup

Alias for service cleanup (--max-count <n>).

Services

service add scaffolds complete local/shared definitions: PostgreSQL and ClickHouse and Redis (local/shared), MySQL (local), and RustFS (shared). Define credentialed cloud, generic, or plugin providers explicitly under services: in .devflow.yml so their required fields are present.

devflow service add [name] [--provider local] [--service-type postgres] [--from <seed>]
devflow service remove <name>              # remove the service config
devflow service list | status | capabilities
devflow service up                         # start all shared global engines (one-shot reconcile)
devflow service create <ws> [--from <parent>]
devflow service delete <ws>                # delete instances; keep the VCS workspace
devflow service start|stop|reset <ws>
devflow service connection <ws> [--format uri|env|json]
devflow service logs <ws> [--tail N]
devflow service seed <ws> --from <file|postgres-url|s3-url>
devflow service discover [--service-type t] [--global]
devflow service cleanup [--max-count N]
devflow service destroy [--force]          # destroy ALL data for a service

Processes

devflow process start [names...] [--all] [--workspace <ws>] [--force]
devflow process stop [names...] [--all] [--workspace <ws>]
devflow process restart [names...] [--all] [--workspace <ws>]
devflow process list|status [--workspace <ws>]
devflow process logs <name> [--workspace <ws>] [--tail N] [--follow]

Processes are workspace-scoped app commands configured under processes.daemons (web servers, workers, schedulers). They run in the worktree, capture stdout/stderr to devflow logs, support dependency ordering, port bumping, and readiness checks, and can interpolate service URLs via MiniJinja ({{ service['app-db'].url }}). processes.auto_start: true makes devflow switch start them after services and hooks; auto-started shell commands use the same approval store as hooks (devflow hook approvals add "npm run dev" or DEVFLOW_APPROVE_HOOKS=1 for automation). processes.provider: native selects the built-in supervisor. Running processes with ports are exposed by devflow proxy as https://<process>.<workspace>.<project>.<suffix> (default .localhost). devflow remove stops them before cleanup. Run devflow daemon start to keep desired-state, watch restart-on-change, and retry reconciliation active in the background. See Project processes for Compose migration patterns and provider details.

Controller daemon

devflow daemon start [--interval 30] [--once] [--foreground]
devflow daemon status
devflow daemon stop

Keeps every registered project’s shared engines running (details) and reconciles managed process desired-state plus watch/retry behavior.

Hooks

devflow hook show [phase]
devflow hook run <phase> [name] [--workspace <ws>]
devflow hook explain [phase]
devflow hook vars [--workspace <ws>]
devflow hook render "<template>"
devflow hook approvals [list|add <template>|clear]
devflow hook triggers                  # VCS event → phase mapping
devflow hook actions                   # built-in action types
devflow hook recipes                   # list + per-project detection
devflow hook setup                     # wizard: install detected recipes
devflow hook install <recipe> [--param KEY=VALUE]... [--yes]

AI & automation

devflow agent status | context [--format json] [--workspace <ws>]
devflow agent skill                    # install bundled workspace helper skills
devflow capabilities                   # machine-readable automation contract

Reverse proxy

devflow proxy start [--daemon] [--https-port 443] [--http-port 80] [--api-port 2019]
                    [--domain-suffix localhost] [--no-mdns] [--no-auto-network]
devflow proxy stop | status | list
devflow proxy trust verify | info

See the proxy guide.

Setup & maintenance

devflow init [path] [--name <n>] [--force]    # initialize (additional workspaces are always materialized)
devflow destroy [--force]                     # tear down the whole project (irreversible)
devflow config [-v]                           # merged config (+ precedence details)
devflow doctor                                # diagnostics: docker, vcs, config, storage, hooks
devflow install-hooks | uninstall-hooks       # git hooks: post-checkout, pre-commit
devflow shell-init [bash|zsh|fish]            # print the auto-cd wrapper
devflow worktree-setup                        # set up devflow inside a manually created worktree
devflow gc [--list] [--all] [--force]         # detect/clean orphaned projects and leftover state
devflow tui                                   # terminal dashboard
devflow plugin list | check <name> | init <name> --lang bash|python

Environment overrides

DEVFLOW_CONTEXT_BRANCH=<ws> overrides the context workspace used as default parent — useful in CI. The full table is in Environment variables.

Baselines, execution and recovery

devflow baseline prepare clean --service db --from fixtures/base.sql --validate fixtures/check.sql
devflow --json baseline list
devflow baseline inspect baseline:clean@v1
devflow switch -c agent/task --from main --data-from baseline:clean@v1
devflow exec --workspace agent/task -- pytest -k 'login or signup'
devflow exec --workspace agent/task --shell 'npm test && npm run build'
devflow operation list --history
devflow operation inspect OPERATION_ID
devflow --json --non-interactive operation resume OPERATION_ID
devflow baseline remove baseline:clean@v1

Program arguments after -- remain literal arguments. Shell syntax requires --shell; switch -x 'command with spaces' keeps its legacy shell spelling when no trailing argument vector is supplied. Required setup must finish before execution. Optional hook failures produce warnings; required: false background hooks record completion separately.

Operations persist stable project identity, saved intent, attempts, steps, per-service checkpoints and bounded history. Resume supports workspace switch/removal and service start/stop/reset/cleanup. Failed seed and baseline preparation require inspection and an explicit retry or replacement; arbitrary SQL and shell hooks may have partial effects.

Retention and project identity

devflow --json retention plan --service db --max-count 10
devflow retention pin agent/long-task
devflow retention expire agent/short-task 2026-12-01T00:00:00Z
devflow --json retention apply --service db --max-count 10
devflow retention unpin agent/long-task
devflow project list
devflow project relocate /old/repository /new/repository

Relocation updates registered paths while preserving project/workspace/service IDs, resource namespaces and operation history. It does not move files or repair Git’s linked-worktree metadata; perform the repository move and any required git worktree repair first.