CLI reference

Use the documentation for the installed version. This reference describes the 0.7.0-beta line.

Open beta · 0.7.0-beta.1

Setup does not start workers, grant runtime access, or authorize connected actions.

Keep your project out of iCloud Drive folders. Project commands such as bowerloom up, ls, status, apply, and skills sync refuse a project under ~/Documents or ~/Desktop when Desktop and Documents sync is on, and under the ~/Library cloud folders, with PROJECT_IN_CLOUD_FOLDER. The older forms that take an explicit path do not run this check. This beta reads skills only from public sources. See the beta limits.

Workers do not start in this beta.

Discovery

After meeting installation requirements, read:

bowerloom --version
bowerloom --help
bowerloom help <command>
bowerloom help advanced

bowerloom --help lists the commands you use first. bowerloom help <command> shows the full help for up, ls, status, skills, apply, team, skill, prompt, and init. bowerloom help advanced lists every form, including the request-file forms and the plumbing commands below. A command followed by --help shows the same text as help <command>.

Bare bowerloom prints the short help. An unknown command prints Unknown command <word>. Run bowerloom help. The help heading reads open beta.

The version output reads Bowerloom 0.7.0-beta.1. Command syntax does not grant execution permission.

Approvals and exit codes

Every command that changes a project shows a plan first. The plan ends with a revision, a 64-character lowercase hex value that names that exact plan.

• In a terminal, the command asks Apply plan <short revision>? [y/N], plans again, and applies only if the revision is unchanged.
• With --approve <revision>, the command applies once and never asks. A revision that no longer matches refuses with STALE_APPROVAL and changes nothing.
• With --json, or without a terminal, the command prints the plan and its revision and exits 3. Nothing is written.
• Pass --approve once. There is no --yes and no -y. Either one is a usage error, exit 2, and no environment variable changes that.

Exit code	Meaning
0	Done, or nothing to change.
1	Refused. The refusal code names the reason.
2	Usage error. The command line did not match a Bowerloom command.
3	Approval required. Read the plan, then run the same command with --approve <revision>.
4	Held by a gate. up returns 4 with prepared, workers held, or prepared, N items held with a next command for each item.
130	You stopped at the yes/no question with Ctrl-C or Ctrl-D. It prints Stopped. Nothing was changed.

In a terminal, a refusal prints its code, a plain sentence, and a Next: line. Without a terminal, a refusal prints one line of JSON on standard error: {"error":{"code":"...","message":"..."}}. Agents parse that line. Errors lists the codes.

Project commands

These commands work in a project folder. The project is the nearest parent folder that holds .bowerloom, found the way git finds .git. The search stops at your home folder. A project in a cloud-synced folder refuses with PROJECT_IN_CLOUD_FOLDER. A home folder or a whole disk refuses with PROJECT_ROOT_REFUSED.

bowerloom up --team <name> [--goal <goal>] [--name <project-name>] [--approve <revision>] [--json]
bowerloom ls [teams|skills|prompts] [--json]
bowerloom status [--json]

up prepares the project one step at a time and starts no workers. See Install Bowerloom. With --json, each line is one JSON object, and each step plan names its step and team. up never edits AGENTS.md or CLAUDE.md, and it never runs claude, codex, or any other program. up ends at prepared, workers held. When a skill, prompt, or team is held or gone, it ends at prepared, N items held and prints a next command for each item.

ls reads the names of teams, skills, and prompts in .bowerloom and writes nothing. An empty section shows none yet. A link, a stray file, or a name that is not a plain id counts as Not listed, and ls never follows it. With --json, ls and ls skills also print pinned, a list of the pinned skill ids. pinned is null when .bowerloom/skills.json cannot be read. Run bowerloom skills check then. A folder with more than 256 entries refuses with INSPECTION_LIMIT.

status shows the project folder, the setup state, any drift, and any skill you edited by hand. It reads only. It prints Workers: none started (this beta starts none). With --json it prints one object with status, revision, drift, owned, runtimeReady, and executionAuthorized. status names each held or missing skill, prompt, or team with its next step. A deleted prompt or team is held. Run bowerloom prompt create <id> to restore a registered prompt that was deleted. Restore a deleted team from version control. A skill installed by an earlier Bowerloom shows as Legacy managed skill: .bowerloom-skills, with the migrate command.

bowerloom status --installation <private.json> still reads a prepared session. See Historical demo and session.

Create commands

bowerloom team create <name> [--profile engineer|founder|research] [--approve <revision>] [--json]
bowerloom skill create <name> [--team <team>]... [--approve <revision>] [--json]
bowerloom prompt create <name> [--team <team>]... [--approve <revision>] [--json]

Agents use these commands most. They write inside .bowerloom only. You and your agents own the files they make. Create teams, skills, and prompts explains each one.

Apply

bowerloom apply [--harness claude|codex|both] [--approve <revision>] [--json]

skills sync already copies the skills in .bowerloom/skills.json into place. apply puts the prompts in .bowerloom/prompts in place for Claude Code, Codex, or both (the default), and it places any skill copy that is still missing. Claude Code and Codex are the harnesses, the agent applications that read these copies. Run apply when the project has prompts. When every copy is already in place, it prints Nothing to change. and exits 0. It never fetches. It adds copies and removes none. It never overwrites a copy you changed. It never edits AGENTS.md or CLAUDE.md. The plan shows a note for a prompt that sets allowed-tools, registers hooks, or runs shell commands. Read that prompt before you approve. See Add third-party skills.

First setup

bowerloom init plan --mode new|existing --target <absolute-directory> --name <project-name> --goal <goal> [--profile engineer|founder|research] [--assistant <name>] [--team <name>] [--review milestones|handoff] [--json]
bowerloom init apply --mode new|existing --target <absolute-directory> --name <project-name> --goal <goal> [--profile engineer|founder|research] [--assistant <name>] [--team <name>] [--review milestones|handoff] --approve <revision>
bowerloom init plan --mode new|existing --target <absolute-directory> --brief <brief.json> [--json]
bowerloom init apply --mode new|existing --target <absolute-directory> --brief <brief.json> --approve <revision>
bowerloom init status --target <absolute-directory>
bowerloom init demo-plan --target <absolute-directory> --from <installed-revision> [--json]

Plans describe files. Apply requires unchanged inputs and exact approval. Status reads the installation. Demo-plan describes a synthetic handoff without execution.

First-team tutorial and Existing project explain the sequence. A stale approval requires another plan.

Revision

bowerloom revise plan --target <absolute-directory> --brief <brief.json>
bowerloom revise apply --target <absolute-directory> --brief <brief.json> --from <installed-revision> --approve <plan-revision>
bowerloom revise recover --target <absolute-directory> --approve <plan-revision> --action resume|rollback

Apply requires the old installed revision and exact new plan approval. Recovery uses the recorded transaction and original approval. It starts no workers.

The parser also accepts inline name, goal, profile, assistant, team, review, and plan --json. Do not mix inline fields with --brief. Read Revision and Recovery.

Control and stop

bowerloom control plan|register --root <root> --team <id> --spec <relative-team-file> [--adapter graph|recipe --installation <private.json>] [--registry <directory>] [--approve <revision>]
bowerloom destruct <team-id> --root <root> [--registry <directory>] [--timeout-ms <milliseconds>]
bowerloom destruct all [--registry <directory>] [--timeout-ms <milliseconds>]

Control records a separately reviewed owner. Registration needs its exact approval. It does not start work. Destruct requests a stop within the selected registry.

A missing owner or uncertain result is not proof of cleanup. Keep the original enrollment and records. Read Stop registered work.

Local definition links

bowerloom link plan --from <root> --to <root> --file <definition> --out <private-new-file>
bowerloom link apply --from <root> --to <root> --file <definition> --out <private-new-file> --approve <revision>
bowerloom link read --connection <file> --target <receiving-root>
bowerloom link revoke --connection <file>

Links disclose one selected definition between reviewed installed local roots. Apply requires the exact file and recipient binding. Read and revoke use the private connection record.

A link grants no execution authority. Changed source, recipient, expiry, or file binding requires inspection and renewed approval. Do not share raw receipts.

Synthetic harness configuration

bowerloom harness import --harness codex|claude --file <absolute-fixture-file> --synthetic
bowerloom harness plan --harness codex|claude --file <absolute-fixture-file> --neutral <private-json-file> --synthetic
bowerloom harness managed-plan --harness codex|claude --file <absolute-fixture-file> --neutral <private-json-file> --state <new-private-directory> --synthetic
bowerloom harness apply --harness codex|claude --file <absolute-fixture-file> --neutral <private-json-file> --state <new-private-directory> --synthetic --approve <revision>
bowerloom harness removal-plan --state <private-directory> --synthetic
bowerloom harness remove --state <private-directory> --synthetic --approve <removal-plan-revision>
bowerloom harness recover --state <private-directory> --synthetic --approve <recorded-operation-revision>

Import and plan read separately reviewed synthetic inputs. Approved projection and removal change the selected fixture. Projection writes the selected files into that fixture configuration. Recovery requires its recorded operation approval.

The --synthetic flag is an assertion. If a file is live or unreviewed, stop. Read Codex and Claude Code.

MCP planning

bowerloom mcp plan --declaration <absolute-json-file> --binding <absolute-json-file> --catalog <absolute-json-file> --synthetic

This form reads three reviewed synthetic files and prints a private plan. It starts no server, resolves no secret, and invokes no tool.

Keep private bindings and output private. Catalog descriptions remain untrusted data. Read MCP connections.

Local backend

bowerloom backend doctor
bowerloom backend plan|install --root <new-absolute-directory> [--studio-port <port>] [--database-port <port>] [--approve <revision>]
bowerloom backend status --root <private-installation-directory>

Doctor inspects prerequisites. Plan describes a separate Supabase installation. Install needs exact approval and starts the named services. Status reads retained state.

The macOS Docker context, ARM64 daemon, Compose v2, storage, and approval requirements remain separate. Read Local backend.

Third-party skills

bowerloom skills add npm:<package>@<version>:<path> [--id <id>] [--team <team>]... [--replace] [--approve <revision>] [--json]
bowerloom skills add github:<owner>/<repo>@<40-char-commit>:<path> [--id <id>] [--team <team>]... [--replace] [--approve <revision>] [--json]
bowerloom skills check [--json]
bowerloom skills sync [--offline] [--team <team>] [--approve <revision>] [--json]
bowerloom skills recover plan|apply --item <id> [--action resume|rollback|abandon] [--approve <revision>] [--json]
bowerloom skills migrate plan|apply --state <earlier-state-folder> [--approve <revision>] [--json]

skills add pins one skill in .bowerloom/skills.json. The pin must be exact. An npm source takes an exact version such as 1.2.3. A GitHub source takes a full 40-character lower-case commit, and the repository name is lower case. Ranges, tags, branches, and short commits refuse before anything is fetched. <path> is the skill folder inside the package or repository. skills add reads only registry.npmjs.org or api.github.com, without credentials. It takes MIT and Apache-2.0 skills only. It records the pin and installs nothing.

--id sets the entry id. The default is the skill name. --team limits the skill to a team. Without it, every team gets the skill. --replace moves an existing id to another version or commit of the same package or repository. The plan shows the old pin and the new pin, and the entry keeps its teams unless you pass --team. Then skills sync updates the copies. Move a skill to a newer pin shows an example.

skills check reads .bowerloom/skills.json and checks every pin offline. It writes nothing.

skills sync installs every skill in skills.json for Claude Code and Codex into .bowerloom/managed, .claude/skills, and .agents/skills. It fetches only pins that the private cache does not hold yet, and it checks every byte against its pin first. --offline refuses before any change if a pin still needs fetching. --team syncs only that team's skills. A skill whose copy you changed is held and shown with its next step, and the others apply. Sync removes nothing. Ctrl-C stops it between two skills, never inside one.

skills recover finishes or undoes the one unfinished change of an item, after a crash or a refusal inside it. skills migrate moves a skill that an earlier Bowerloom installed in .bowerloom-skills to .bowerloom/managed. skills.json must pin the same source first. migrate plan prints the skills add command if it does not.

Add third-party skills explains the sequence and the refusal codes. bowerloom help skills shows the same forms.

Request-file forms

These older forms take hand-written request files. bowerloom help advanced lists them. The skills add, sync, and apply commands above replace them for everyday use.

bowerloom skills source plan --request <absolute-json> --state <private-root> --operation <id> --min-free-bytes <integer>
bowerloom skills source acquire --plan <absolute-json> --approve <revision>
bowerloom skills source git plan --request <absolute-json> --state <private-root> --operation <id> --min-free-bytes <integer>
bowerloom skills source git acquire --plan <absolute-json> --approve <revision>
bowerloom skills source inspect --request <absolute-local-cache-selector-json>
bowerloom skills source recover plan --request <absolute-json>
bowerloom skills source recover apply --plan <absolute-json> --approve <revision>
bowerloom skills plan --request <absolute-install-request-json>
bowerloom skills update plan --request <absolute-update-request-json>
bowerloom skills apply --plan <absolute-json> --approve <revision> --previous <revision|none>
bowerloom skills inspect --request <absolute-json>
bowerloom skills recover plan --request <absolute-json>
bowerloom skills recover apply --plan <absolute-json> --approve <revision>

These forms read public npm and public GitHub sources only. skills recover takes --item for the new forms and --request for the request-file forms.

Routine planning

bowerloom routine plan --root <absolute-.bowerloom-directory> --experiment-id <logical-id> --experiment-digest <sha256:hex>

Routine planning describes a routine. It starts no workers.

Portable bundles

bowerloom portable validate <bundle-directory>
bowerloom portable plan|install <bundle-directory> --select <part,part> --harness codex|claude --target <new-absolute-directory> [--approve <revision>]

These forms require a separately reviewed bundle and selected parts. Approved installation copies selected files into a new target. It starts no workers.

The portable installer accepts codex and claude. Any other value fails with UNSUPPORTED_HARNESS. The codex value projects skills into .agents/skills/. The claude value projects them into .claude/skills/bowerloom-<part-id>/. Claude Code has not been observed to discover these files natively. The installer does not establish general harness conversion. An existing target or stale approval requires inspection.

Recipe controller

bowerloom recipe inspect|setup --installation <private.json>
bowerloom recipe plan|review|approve|run|reconcile|cancel|status --installation <private.json> --input <request.json>

These forms require the exact private installation, input, operator authority, and accepted recipe scope. They are not a general startup procedure.

The operator CLI owns exact approval. An uncertain external result requires reconciliation of the original operation. Do not replay it blindly.

Team source

bowerloom validate <crew.yaml> [--root <directory>]
bowerloom plan <crew.yaml> [--root <directory>]

These forms read crew.yaml and print JSON. The source root defaults to its containing directory. They start no workers.

Use a separately scoped source tree. Successful validation does not grant runtime permission or prove a model sandbox.

Scenario authoring

bowerloom authoring validate|export <authoring.json> --scenario <frozen-scenario.json> [--root <directory>]

These forms require a separately frozen supported scenario. They compile the selected authoring input for that scenario.

An export is not an executed experiment. Preserve the scenario and source-license requirements in Workbench.

Historical demo and session

bowerloom up --demo --pro|--5x|--20x --installation <private.json>
bowerloom status|review|cancel --installation <private.json>
bowerloom approve --installation <private.json> --candidate <sha256:...> --action <sha256:...>

These forms require a private prepared installation and separately accepted execution scope. They do not replace first-team setup.

Up stops for exact approval. Approve writes and tests the stored proposal. Tier flags do not promise measured throughput. The task runner executes sequentially.

Flags and refusal

init plan --json and revise plan --json expose the complete plan. Apply requires the exact reviewed revision, not a guessed value.

Malformed, duplicate, extra, or conflicting arguments refuse. Do not infer success without reading the actual result.

The CLI has no generic init recover, public MCP connect command, or general native bootstrap command.

Compatibility aliases

trellis and trellis-mcp remain compatibility aliases. They do not expose a different authority or qualify an older runtime path.

Support boundary

Current support describes supported tasks and limits. Status and error reference explains core refusals.