DockPipe

CLI reference

Use dockpipe -- <command> for a one-off command or dockpipe --workflow <name> -- for a workflow you created or installed.

Run → isolate → act. Overrides use the same names as workflow YAML. Precedence: CLI > config > environment.

For most users, the main knobs are:

  • --workflow — which workflow to run
  • --runtime — where it runs
  • --resolver — which tool/profile it uses

Treat --isolate as the low-level image/template override, not the main way to think about workflow selection.

Prerequisites: native host steps need Bash; container workflows need a reachable engine. Git is needed for Git operations. Flatpak supplies its shell/container clients and uses explicit host integrations where required. See installation.

Workflow YAML (config.yml): single-command layout (run / isolate / act) or multi-step steps: (ordering, outputs:, explicit group.mode: async for parallel work). In step mode, top-level run / act are not used. Full reference: workflows/workflow-yaml.md.

Main subcommands: dockpipe init, dockpipe build|clean|rebuild, dockpipe package, dockpipe workflow validate|list|test, dockpipe test, dockpipe doctor, dockpipe windows setup|doctor, and optional maintainer/publishing commands such as dockpipe install core, dockpipe release upload, and dockpipe pipelang ....

If you just want the common path:

  • dockpipe --workflow <name> -- ... runs a workflow
  • dockpipe init creates a starter project/workflow layout
  • dockpipe workflow validate <config.yml> checks authored YAML
  • dockpipe test runs package-owned tests plus workflow-local tests
  • dockpipe doctor checks bash, Docker, and bundled assets

Use an installed CLI from your own project folder. For Flatpak, replace dockpipe with flatpak run --command=dockpipe com.dockpipe.Dockpipe.

The detailed sections include optional package-author and self-hosted publishing commands. They are not steps required to install or use Dockpipe.

Remote workers

dockpipe remote provides provider-neutral setup, pairing, outbound workers, explicit workflow submission (including source/assets/package delivery with --workflow-file), cancellation, and result download. Workers explicitly opt in with remote pair --allow-delivery; existing profiles remain supported. See Remote nodes for the Cloudflare resolver, local profiles, credentials, recovery, and current qualification limits.

dockpipe init

Local project setup only: no git clone, no treating init as a remote bootstrap. Everything runs in the current working directory.

Command Purpose
dockpipe init Create the minimal project scaffold: workflows/, README.md, dockpipe.config.json, and .env.vault.template.example when missing. If no Dockpipe workflows exist yet, also create workflows/example/config.yml as a starter. It does not copy templates/core/, scripts/, or images/ into the project.
dockpipe init <name> Create workflows/<name>/config.yml as a minimal empty workflow (name + description only). Does not copy the bundled init template unless you pass --from init. If workflows/ already exists but has no */config.yml trees, the CLI prints a warning (often a conflict with GitHub Actions).
dockpipe init <name> --workflows-dir <path> Put the new workflow under <path>/<name>/ instead of workflows/ (repo-relative or absolute). Same as env DOCKPIPE_WORKFLOWS_DIR for dockpipe run.
dockpipe init <name> --from <source> Copy into workflows/<name>/ (or --workflows-dir): --from may be blank, init, another bundled name (resolved under templates/&lt;name&gt; or the bundled workflows root), or a filesystem path (e.g. workflows/&lt;name&gt; in a dockpipe checkout). Not a Git URL.
dockpipe init <name> --resolver <n> --runtime <n> --strategy <n> Optional; written into the new config.yml. New workflows use plain resolver: and runtime:. Example: dockpipe init my-pipeline --from run-apply --resolver codex --runtime dockerimage.
dockpipe init --gitignore Opt-in only: append a marked block to .gitignore at the git repository root (bin/.dockpipe/, Go caches, tmp/). Idempotent if the block is already present. Requires a git working tree (run from inside a repo).

Named workflows normally live at workflows/<name>/config.yml in your project. Installed packages and configured source roots are also searched. Override the primary source folder with --workflows-dir or DOCKPIPE_WORKFLOWS_DIR; use --workflow-file when you want an exact file. Legacy templates/<name>/config.yml remains a compatibility fallback.

dockpipe init creates the root README.md when missing and ensures workflows/ exists.

dockpipe install

Fetches a published templates/core tree over HTTPS and replaces <workdir>/templates/core. This is a legacy core-tree/mirror command, not the normal application installer or Marketplace package install. Intended for packages hosted on Cloudflare R2 (or any static HTTPS origin); credentials are not required for public URLs.

Command Purpose
dockpipe install core --dry-run --base-url <https://…> Show resolved URLs only.
dockpipe install core --base-url <https://…> latest: GET <base>/install-manifest.json, follow packages.core, verify sha256, extract.
dockpipe install core --base-url <https://…> --version 0.6.0 GET <base>/templates-core-0.6.0.tar.gz (+ optional .sha256).
dockpipe install core --url <https://…/file.tar.gz> Direct tarball URL; optional --sha256 or sibling .sha256.

Environment: DOCKPIPE_INSTALL_BASE_URL, optional DOCKPIPE_INSTALL_VERSION, DOCKPIPE_INSTALL_MANIFEST (default install-manifest.json), DOCKPIPE_INSTALL_ALLOW_INSECURE_HTTP=1 for http:// (local tests only).

For archive construction and self-hosted publication, see Package publishing. Application users should use the installation guide and dockpipe package install below.

dockpipe clone

Command Purpose
dockpipe clone <name> [--workdir <path>] [--to <dest>] [--force] Copy bin/.dockpipe/internal/packages/workflows/<name>/ to --to (default <workdir>/workflows/<name>) only if package.yml has allow_clone: true. Refused when allow_clone is false or omitted (typical for commercial binary-only drops).

See packages/package-model.md (Clone, education, and commercial packages).

dockpipe build / clean / rebuild

Project build and cleanup commands (see packages/package-model.md).

Command Purpose
dockpipe build [options] Rebuild the compiled package/workflow store under bin/.dockpipe/internal/packages/ for the current project. In practice this is the main “refresh compiled state” command. It also materializes configured PipeLang roots and prebuilds Dockerfile-backed image artifacts unless you pass --no-images. If --workdir is omitted, the project directory is the folder containing dockpipe.config.json (walking up from the current directory), or the current directory if that file is absent. Options: --workdir, --for-workflow <name>, --images, --no-images.
dockpipe clean [--workdir <path>] [--dry-run] Preview or remove the complete checkout-local disposable tree at <workdir>/bin/.dockpipe. Dry-run reports the exact resolved target, logical bytes, file count, and action without mutation. A missing tree is a reported no-op. Ordinary clean never follows DOCKPIPE_PACKAGES_ROOT outside the checkout.
dockpipe rebuild [options] Separately reset the resolved compiled store, including DOCKPIPE_PACKAGES_ROOT, then run build. The reset is reported and rejects filesystem roots, home/workdir authority, durable state, links/reparse points, filesystem substitutions, and unsafe trees.

Clean accepts only its exact checkout-local target. It rejects parent traversal, filesystem-root workdirs, workdir/ancestor or durable-state targets, links/reparse points, special files, and filesystem substitutions. Durable package state resolved by dockpipe scope --package remains outside the disposable tree and survives ordinary clean. Rebuild retains its separate guarded reset of the resolved compiled store for DOCKPIPE_PACKAGES_ROOT compatibility.

dockpipe package

Discover and install remote packages, inspect local inventory, or compile your own workflows. Remote installation uses the per-user store; project compilation uses bin/.dockpipe/internal/packages/. See Find and use packages for the normal install/run path and Package model for advanced authoring and storage.

Command Purpose
dockpipe package list [--workdir <path>] Print project-store package metadata in text form; use --format json for inventory across project, configured, user and system stores, with warnings.
dockpipe package list --format json [--workdir <path>] Inventory project, configured, user, and system packages, plus warnings and the user install root.
dockpipe package catalog --remote <HTTPS manifest URL> Return the current execution platform's remote packages and resolved store manifest as JSON. Inside Flatpak this includes its runtime ID/branch; native processes retain OS/architecture selection. Accepts a latest pointer, release catalog, or explicit platform store.
dockpipe package install --remote <URL> --kind core|workflow|resolver --name <name> [--sha256 <digest>] Verify and install one package into the user store. A digest pins the selected catalog entry. Dependencies are installed separately.
dockpipe package uninstall --path <absolute archive path> Remove one optional user-store archive. Core, external stores, directories, and symlinks are protected; package data and settings are retained.
dockpipe package images [--workdir <path>] Merge planned image artifacts from compiled workflow tarballs with materialized/cached receipts under bin/.dockpipe/internal/images/by-fingerprint/; print fingerprint, status, state, source, image_ref, workflow, package, step_id, image_key (tab-separated). Status can show ready, missing, stale, planned, referenced, or docker-error.
dockpipe package manifest Print an example package.yml (schema: name, version, title, description, author, website, license, optional kind).
dockpipe package build core [--repo-root <path>] [--out <dir>] [--version <ver>] Write templates/core tarball (core/… prefix), .sha256, install-manifest.json for dockpipe install core. Default --out: release/artifacts/.
dockpipe package test [--workdir <path>] [--only <package>] Run package-owned tests for packages in the current source checkout that declare test.script in package.yml.
dockpipe package build store [--workdir <path>] [--out <dir>] [--only <slice>] [--version <ver>] Gzip tar per compiled package under bin/.dockpipe/internal/packages/ (after dockpipe build), archive paths core/, workflows/<name>/, resolvers/<name>/. --only bundles adds bundle packages. packages-store-manifest.json lists artifacts. Default --out: release/artifacts/.
dockpipe package compile workflow <source-dir> [--workdir <path>] [--name <n>] [--force] workflow validate on source-dir/config.yml, then copy the tree to bin/.dockpipe/internal/packages/workflows/<name>/ (writes package.yml if missing, with allow_clone: true and distribution: source for local round-trips).

Environment: DOCKPIPE_PACKAGES_ROOT — override the compiled package root (default <workdir>/bin/.dockpipe/internal/packages) for compile/build/rebuild. It does not relocate durable package state and ordinary clean does not use an external override.

dockpipe workflow test and dockpipe test

Workflow-local tests are discovered from on-disk workflow directories that contain one of:

  • tests/run.sh
  • tests/run.ps1
  • tests/run.cmd
  • tests/run.bat

Commands:

Command Purpose
dockpipe workflow test [--workdir <path>] [--only <workflow>] Run workflow-local tests for workflows discovered from the current project/workdir.
dockpipe test [--workdir <path>] Umbrella test command: run dockpipe package test plus dockpipe workflow test.
dockpipe test --only <name> Limit the umbrella run to one matching package/workflow name when applicable.

dockpipe pipelang

Optional typed authoring helper. PipeLang compiles to inspectable artifacts; workflow execution still uses normal Dockpipe YAML.

When a workflow also declares view:, that YAML remains a launcher/tooling presentation layer over the typed model rather than a separate execution contract. See concepts/pipelang.md and workflows/workflow-yaml.md.

Command Purpose
dockpipe pipelang check --in <file.pipe> [--format text|json] [--stdin] Strictly decode, parse, and type-check the source set without evaluating code or emitting artifacts. JSON is the stable structured diagnostic projection; --stdin replaces the selected file bytes for unsaved editor buffers.
dockpipe pipelang compile --in <file.pipe> [--entry <Class>] [--out <dir>] Parse + type-check PipeLang and emit artifacts: <Class>.workflow.yml, <Class>.bindings.json, <Class>.bindings.env (default out: bin/.dockpipe/pipelang/).
`dockpipe pipelang invoke --in <file.pipe> [--class <Class>] --method <name> [--arg <value>]... [--format text json
dockpipe pipelang materialize [--workdir <path>] [--from <root>]... [--force] Recursively compile .pipe files under roots into sidecar .pipelang/ artifacts. Default roots are resolved from dockpipe.config.json compile.workflows.

Method support (v0.0.0.1): expression-bodied methods are parsed, type-checked, included in bindings metadata, and invocable only via dockpipe pipelang invoke.

dockpipe release

Upload a single file to an S3-compatible bucket (e.g. Cloudflare R2) using the aws CLI. Requires AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (or compatible credentials). Not required for official Dockpipe distribution; use for self-hosted package mirrors.

Command Purpose
dockpipe release upload <local-file> [--bucket <name>] [--key <object-key>] [--endpoint-url <url>] [--region <name>] [--content-type <ct>] [--dry-run] aws s3 cp to s3://bucket/key. Bucket: --bucket or DOCKPIPE_RELEASE_BUCKET or R2_BUCKET. Endpoint: --endpoint-url or R2_ENDPOINT_URL / AWS_ENDPOINT_URL_S3, or derive https://<id>.r2.cloudflarestorage.com from CLOUDFLARE_ACCOUNT_ID / R2_ACCOUNT_ID. Key defaults to the file’s basename.

Workflow variables (--workflow)

When you use --workflow <name>, the resolved config.yml (see workflows/workflow-yaml.md for lookup order) may include a top-level vars: block: indented KEY: value lines. Those names are exported before run scripts, only if they are not already set in your shell (so your environment and CI secrets win).

Additional sources (each only sets unset variables, except --var):

  1. vars: defaults in config.yml
  2. .env beside the resolved workflow config.yml (e.g. workflows/<name>/.env, src/core/workflows/<name>/.env)
  3. .env at the bundled materialized root (default: user cache; layout under install.md) or at DOCKPIPE_REPO_ROOT if you set it
  4. Each --env-file <path> (in order)
  5. Path in DOCKPIPE_ENV_FILE if set
  6. --var KEY=VAL (always exported; overrides yml and .env)

Use --var for one-off overrides; use .env files for local secrets and team defaults.

Flags

All options must appear before a standalone --. The command and its arguments follow --.

--workdir: Optional. If omitted, the project directory is the current working directory (PWD). Typical local use: cd to the repo root and run dockpipe with no --workdir. Use --workdir <path> when the process is not started from that directory (CI, make, wrappers) or when you want an explicit path without cd.

Flag Aliases Purpose
--workflow <name> Load a named workflow. The normal lookup path is project workflows/, configured package/workflow roots from compile.workflows, and bundled workflows included with the Dockpipe build. Legacy templates/ and some maintainer/example roots remain as compatibility fallbacks. With steps:, a final -- is optional (see workflows/workflow-yaml.md). Mutually exclusive with --workflow-file.
--workflow-file <path> Load workflow YAML from an arbitrary path (same shape as bundled config.yml). Relative run: / act: paths resolve next to that file. Resolver profiles use the configured package/core lookup, not arbitrary folders beside the YAML file. Mutually exclusive with --workflow.
--package <name> With --workflow <name>, select an unpacked packaged workflow whose nearest package.yml has matching name:. This is a generic package selector, not an AI-provider concept. Mutually exclusive with --workflow-file.
--workflows-dir <path> Repo-relative or absolute directory for --workflow <name> resolution (default workflows/). Same as DOCKPIPE_WORKFLOWS_DIR. Also dockpipe init <name> --workflows-dir ….
--run <path> --pre-script Run: script(s) on the host before the container. Repeatable.
--isolate <name> --template, --image Low-level image/template override. Builds if the value is a template. Prefer --runtime + --resolver for the normal path, and use --isolate when you need to pin the exact image/template.
--act <path> --action Act: script after the container command (e.g. commit-worktree).
--runtime <name> Main where does this run? flag. Selects a runtime profile from templates/core/runtimes/<name> or bundle/core/runtimes/<name>. May be combined with --resolver.
--resolver <name> Main which tool/profile does this use? flag. Selects a resolver profile from templates/core/resolvers/<name> or bundle/core/resolvers/<name> (or …/profile under the same dir). Often used with --repo / worktree flows. Both flags may be set; the runner merges the two files.
--strategy <name> Named lifecycle wrapper from templates/<workflow>/strategies/<name> or workflows/<workflow>/strategies/<name> (optional) or templates/core/strategies/<name> / bundle/core/strategies/<name> (bundle cache): runs before / after host scripts around the workflow body. Overrides strategy: in workflow YAML when both are set.
--repo <url> Clone URL for worktree flows. If omitted and the workflow uses clone-worktree.sh, dockpipe sets the URL from git remote get-url origin in the current dir (or --workdir). When that URL matches your origin, the worktree can be created from your local checkout (not only a fresh remote default).
--branch <name> Explicit work branch for --repo (optional).
--work-branch <name> When --repo is set and --branch is omitted, use this as the full branch name. If both are omitted, dockpipe generates prefix/<adj>-<noun>-<adj>-<noun> (random hyphenated slug; prefix from resolver / template — see domain.RandomWorkBranchSlug in branchslug.go). If --branch is set, it takes precedence over --work-branch.
--workdir <path> Host path mounted at /work. Default: current directory (see note above — omit when you cd to the project first).
--work-path <path> Subdirectory inside the repo used as the container working directory (/work/<path>).
--bundle-out <path> After commit-on-host, write a git bundle here (default: current branch only). Set DOCKPIPE_BUNDLE_ALL=1 for git bundle create … --all.
--env KEY=VAL Pass env into the container. Repeatable. When /work is a git worktree, dockpipe also sets DOCKPIPE_WORKTREE_BRANCH, DOCKPIPE_WORKTREE_HEAD, or DOCKPIPE_WORKTREE_DETACHED=1 from the host git view.
--mount <host:container> Extra volume mount. Repeatable.
--data-dir <path> Bind-mount host path for persistent tool data (HOME in container).
--data-vol <name> --data-volume Named Docker volume for persistent data (default: dockpipe-data when neither --data-dir nor --no-data).
--no-data Do not mount a data volume / data dir.
--reinit With a data volume: remove that volume before run (fresh HOME). Confirms on TTY; use -f / --force to skip confirmation.
-f / --force With --reinit, skip confirmation (warning may still print).
--build <path> Parsed (relative to repo root or POSIX absolute). Not currently consumed by the Go runner — image build dirs come from --isolate / template resolution. Kept for CLI compatibility; see CliOpts.BuildPath in flags.go.
--env-file <path> Merge KEY=VAL lines into workflow env (unset keys only unless overridden). Repeatable.
--var KEY=VAL Set workflow var; overrides yaml / .env. Repeatable.
-d / --detach Run the container in the background.
-h / --help Print usage.
--version, -v, -V Print version (handled in main before Run).

Windows subcommands (dockpipe windows …)

Optional. For DOCKPIPE_USE_WSL_BRIDGE=1: install dockpipe in WSL and run dockpipe windows setup / doctor. Native dockpipe.exe users can ignore this. See Optional: WSL bridge in install.md.

Command Purpose
dockpipe windows setup Interactive: select WSL distro, bootstrap env, optional --install-command in the distro.
dockpipe windows setup --distro <name> --non-interactive Scripted setup (--distro required).
dockpipe windows setup --bootstrap-wsl If WSL is missing or has no distros, run wsl --install (default distro Alpine when unset; may UAC / reboot), then continue.
dockpipe windows setup --install-dockpipe Download latest dockpipe_*_linux_*.tar.gz from GitHub into ~/.local/bin in WSL (for the bridge).
dockpipe windows setup --install-command "<cmd>" Run a command inside the selected distro during setup (overrides --install-dockpipe).
dockpipe windows doctor Print wsl --version, list distros and configured default, or hints if WSL is missing.

Windows host: native vs WSL bridge

Default: dockpipe.exe runs on Windows. Docker Desktop supplies docker; bash and git must be on PATH separately (e.g. Git for Windows) — Docker Desktop does not ship them.

Container user: Linux/macOS pass -u with the host uid:gid (overrides USER in the image). If you run dockpipe as root (e.g. sudo), that maps to -u 0:0, which breaks CLIs that refuse flags like --dangerously-skip-permissions as root. For claude / codex / agent-dev images, dockpipe defaults to -u node when the host uid is 0 (unless DOCKPIPE_FORCE_ROOT_CONTAINER=1). Override with DOCKPIPE_CONTAINER_USER.

Windows: host uid is unavailable; dockpipe does not pass -u unless DOCKPIPE_WINDOWS_CONTAINER_USER is set (image USER applies — e.g. node in claude/codex images). Defaulting -u node from the CLI caused bind-mount stalls for some Docker Desktop setups, so use an explicit value when needed: DOCKPIPE_WINDOWS_CONTAINER_USER=node for Claude Code with --dangerously-skip-permissions, or 0 for root.

Claude Code --dangerously-skip-permissions: The CLI blocks that flag when it thinks you’re root/sudo. In Dockpipe that behavior is handled by the resolver image wrappers, not the shared root entrypoint: the claude and codex images set IS_SANDBOX=1 by default (Claude Code’s supported disposable-sandbox mode — see anthropics/claude-code#9184) and re-exec root → node via runuser/setpriv when the container still starts as uid 0. Opt out: DOCKPIPE_NO_SANDBOX_ENV=1 and DOCKPIPE_SKIP_DROP_TO_NODE=1. DOCKPIPE_DEBUG=1 still prints id from the shared entrypoint. Rebuild the resolver image after wrapper changes. DOCKPIPE_WINDOWS_CONTAINER_USER remains available if you want an explicit -u from the host.

Design: loose defaults in isolation. Dockpipe targets disposable containers; resolver-owned images may apply automation-friendly defaults like IS_SANDBOX=1 while the CLI still passes host uid:gid on Unix. People who want stricter behavior can opt out with the env vars above. Dockpipe does not append --dangerously-skip-permissions to your command — add it after -- if you want that mode. Security is mostly what you mount (only /work etc.), secrets in env/volumes, and network — not “CLI tightness” alone.

Windows + host git / Docker mounts: Bash scripts may export DOCKPIPE_WORKDIR as /c/Users/... (Git Bash). Native git.exe and docker -v need normal Windows paths; dockpipe converts MSYS-style paths before git -C, docker run bind mounts, --data-dir, and --mount. If /work looks empty in the container, rebuild with a current dockpipe and confirm the printed Mount /work ← … path exists on the host.

Code edits vs host user: On Linux/macOS, the container usually runs as your host uid:gid, so files written under /work are owned by you on the host (unless you override -u). Claude’s permission model (prompts vs --dangerously-skip-permissions) is application-level; it does not replace POSIX ownership — both apply: the process uid writes files, and Claude may still ask or gate tools unless you pass flags it documents.

WSL bridge (opt-in): set DOCKPIPE_USE_WSL_BRIDGE=1 so every command except dockpipe windows … runs inside WSL via wsl.exe -d <distro>. The current Windows working directory is mapped with wslpath.

Environment: DOCKPIPE_WINDOWS_BRIDGE=1 is set for the inner process when the bridge is used. Windows-style paths in path-like flags (--workdir, --work-path, --data-dir, --mount, --build, --env-file, --run / --act, --isolate / --template / --image when the value is a host path, --env / --var when the value is a path, etc.) and in init / action init / pre init / template init destination args are translated to WSL paths: wslpath -u first, then a drive-letter fallback (C:\… → /mnt/c/…). UNC paths (\\server\share\…) use a fallback that avoids breaking filepath.Clean. Everything after a standalone -- is passed through unchanged.

Examples

Minimal (workflow does the rest):

dockpipe --workflow my-ai --resolver claude --repo https://github.com/you/repo.git -- claude -p "Fix the bug"

Override branch, add env:

dockpipe --workflow my-ai --resolver claude --repo https://github.com/you/repo.git --branch my-feature \
  --env "GIT_PAT=$GIT_PAT" -- claude -p "Implement the plan"

No workflow — override run/isolate/act:

dockpipe --resolver claude --repo https://github.com/you/repo.git \
  --run ./my-run.sh --act ./my-act.sh -- claude -p "Task"

Secret environments

Use --secret-environment NAME with a named entry in dockpipe.config.json → secrets.environments. vault: environment requires the selected/default environment; a missing selection or failed load stops execution. --no-vault disables both environment resolution and legacy template injection. See Secret environments for 1Password, AWS Secrets Manager, Azure Key Vault, and Infisical configuration.