CLI reference

Commands and flags validated against the current Cobra command tree.

This reference is validated against the Cobra command tree in cmd/ and the output of go run . <command> --help. wraptool --help remains authoritative for the binary you have installed.

Top level

Command	Purpose
`wraptool`	In a Git repository, run `up` with defaults; outside one, show help
`wraptool serve`	Start the MCP server
`wraptool up`	Ensure the shared server and enter a project container
`wraptool down`	Stop or remove this worktree’s Dev Container
`wraptool init`	Generate harness MCP configuration
`wraptool init devcontainer`	Scaffold a new Dev Container config
`wraptool harness`	Manage the version-locked harness pool
`wraptool requests`	Review capability requests
`wraptool server`	Inspect or stop the shared server
`wraptool config validate`	Strictly decode and validate configuration
`wraptool doctor`	Run the operator-facing preflight report
`wraptool version`	Print build version, revision, dirty state, and Go version
`wraptool completion`	Generate shell completion for bash, fish, PowerShell, or zsh

--version prints the compact version. version prints the fuller build identity.

Server and container lifecycle

`serve`

wraptool serve [-c|--config PATH]

Config path precedence is flag, WRAPTOOL_CONFIG, then the XDG default. The configured transport determines whether the process uses a TCP HTTP listener or a Unix socket.

`up`

wraptool up [--config PATH] [--no-server] [--no-container]
            [--runtime auto|guix|devcontainer]
            [--shell auto|always|never] [--workspace PATH]
            [--harness NAME]

--runtime defaults to auto; it selects Guix only when guix is on PATH and the worktree contains manifest.scm, otherwise Dev Container. --harness defaults to claude. Orchestration currently requires mcp.transport: sse.

`down`

wraptool down [--workspace PATH] [--rm]

This finds a Dev Container by its workspace label. --rm removes it with force; without the flag it is stopped. Guix containers are transient and are not managed by down. The shared wraptool server remains running.

`server`

wraptool server status [-c|--config PATH]
wraptool server stop

status combines PID-file liveness with TCP reachability. stop sends SIGTERM to the process recorded by the shared PID file.

Client configuration

`init`

wraptool init --harness NAME[,NAME...] [--transport sse|unix]
              [--url URL] [--socket PATH] [--global] [--config PATH]

--harness is required and repeatable; comma-separated values and all are accepted. Known names are agy, claude, omp, opencode, and pi. Project output is merged into each harness’s JSON file when that file contains valid JSON.

Warning

Unix client generation is incomplete: --socket does not create a bridge and most listed harnesses expect an HTTP URL. Use an explicit bridge such as socat or choose TCP.

`init devcontainer`

wraptool init devcontainer [--harness claude|opencode|pi|agy|omp]
  [--lang go,node,java,python,rust] [--base ubuntu|debian|alpine|IMAGE]
  [--out PATH] [--name NAME] [--force]

The command writes a new JSONC file and refuses to overwrite by default. npm harnesses automatically add the Node feature. It is a scaffold, not a merger.

`harness`

wraptool harness list
wraptool harness install HARNESS [--constraint EXPR] [--backend auto|guix|oci]
                                 [--allow-young --reason TEXT]
wraptool harness refresh [HARNESS]
wraptool harness update [HARNESS] [--backend auto|guix|oci]
                                  [--allow-young --reason TEXT]
wraptool harness sync [HARNESS] [--platform KEY] [--backend auto|guix|oci]
wraptool harness rollback HARNESS [--to VERSION] [--platform KEY]
wraptool harness gc [--dry-run] [--legacy]
wraptool harness policy set [--harness NAME]
                            [--minimum-release-age DURATION]
                            [--minimum-observation-age DURATION]
                            [--allow-prereleases]

These commands manage harnesses in the developer harness pool, shared by every project. claude, opencode, pi, agy, and omp are locked and realized in the pool.

omp is a pool-only harness: it has no legacy installer, so install, update, and sync skip that step without a warning, and a realize failure fails the command. It needs no guix, docker, or podman: the pool downloads one release binary per platform and checks it against the release’s SHA256SUMS.txt. The sync --platform option downloads only the named platform. Run wraptool harness install omp before wraptool up --harness omp. The release source locks only versions whose release publishes a checksum file, which starts at omp 17.2.10.

manifest.yaml records which harnesses you want and their version constraints. harness-lock.json records the exact versions they resolved to. A version moves through refresh (candidate metadata), resolve (the lock), fetch (downloads), and realize (an offline-built generation). Activation then points the pool at that generation.

Command	Network	Effect
`list`	none	Show each harness’s constraint, locked, active, latest, and eligible versions, and remaining quarantine
`install`	yes	Record intent, then refresh, resolve, fetch, and realize; keeps an existing lock
`refresh`	metadata only	Record candidate versions in `observations.json`; no download, no lock change
`update`	yes	Lock the newest eligible candidate already refreshed, then fetch and realize it
`sync`	downloads only	Fetch missing or empty downloads for the current lock, then realize it; never resolves
`rollback`	none	Activate a previously realized generation; the lock is not changed
`gc`	none	Remove unreferenced generations, downloads, and staging directories
`policy set`	none	Edit quarantine and prerelease policy in `manifest.yaml`, keeping comments

Without a HARNESS argument, refresh and update act on every harness in manifest.yaml, and sync on every harness in the lock.

Flag	Commands	Default	Meaning
`--constraint EXPR`	`install`	keep existing, else stable	Version constraint, such as `'>=2 <3'` or `'=2.1.220'`
`--backend`	`install`, `update`, `sync`	`auto`	`auto` uses Guix when it can build the target, else Docker or Podman
`--allow-young`	`install`, `update`	off	Bypass quarantine; requires `--reason`, which goes to the pool audit log
`--platform KEY`	`sync`, `rollback`	this host	`linux-amd64-glibc`, `linux-arm64-glibc`, `linux-amd64-musl`, or `linux-arm64-musl`
`--to VERSION`	`rollback`	newest other generation	Exact version to activate
`--dry-run`	`gc`	off	Report what would be removed
`--legacy`	`gc`	off	Also remove the pre-generation `bin/` and `lib/` trees; refused unless every harness is active
`--harness NAME`	`policy set`	pool-wide	Apply the policy to one harness

--backend guix fails for a target architecture other than the host’s. --backend oci fails when neither docker nor podman is on PATH.

Each download prints its size, then progress every five seconds, on stderr. An interrupted install or update reuses downloads that already finished. update does not fetch when the lock is already current, so use sync to repair a missing or empty download.

A later sync, update, or install can re-activate the lock’s own generation and undo a rollback.

Requests and validation

wraptool requests list [--status pending|approved|denied|""]
wraptool requests approve REQUEST_ID [--apply]
wraptool requests deny REQUEST_ID [--reason TEXT]
wraptool admin open [--print]
wraptool config validate [PATH]
wraptool config validate --config PATH

The default request-list filter is pending; an empty status displays all. admin open opens the review UI in the default browser, logged in via its token; --print prints the login URL instead. approve --apply first records approval, then attempts the atomic config edit. If editing fails, request status remains approved while policy remains unchanged.

The positional config path and --config cannot be used together. Validation strictly rejects unknown YAML keys and performs the same semantic checks used by serve, without starting a server or wrapped tools.

Diagnostics

`doctor`

wraptool doctor [-c|--config PATH] [--workspace DIR] [--json]
                [--only CHECK,...] [--skip CHECK,...] [--strict]
                [--no-probe] [--verify-pool]

An operator-facing preflight report: host dependencies, configuration integrity, deployment posture, and policy content. Safe to run before any configuration exists. Exit code 0 means no fail finding, 1 means at least one, and 2 means doctor could not complete. See wraptool doctor for the full report format, check groups, severity model, and suppression syntax.