Command reference

Every bowline command, grouped by intent, with arguments, flags, and JSON output types.

This is the full bowline command reference, grouped the same way as bowline help. Most commands accept --json; mutating commands also accept --dry-run and, where retries are safe, --idempotency-key <key>. See the CLI overview for how those conventions work.

The CLI is self-describing. bowline contract --json returns the canonical, machine-readable contract for every command, including options, examples, JSON output types, and side-effect levels. This page is the human-readable view of that contract.

Discovery

These commands describe the CLI itself. They're read-only and safe to run anytime.

`bowline help`

Show human or JSON help for every command. Topic help works for nested commands.

bowline help [topic...] [--json]
bowline help agent start --json

`bowline version`

Print the CLI version and protocol compatibility. --version is an alias.

bowline version [--json]

`bowline contract`

Print the machine-readable CLI command and output contract. bowline schema is an alias for discoverability.

bowline contract --json
bowline schema --json

Workspace

These commands set up your workspace, report state, and explore project content.

bowline login [--root <path>] [--headless] [--no-poll] [--json]

--root <path>: choose the workspace root (for example, ~/Code).
--headless: run without opening a browser, for remote hosts.
--no-poll: skip polling for authentication completion.

`bowline init`

Initialize or observe a workspace root. With no path, it creates or inspects the default ~/Code root.

bowline init [path] [--json]

`bowline status`

Inspect workspace, index, sync, and safe next actions. Defaults to the current project, with a compact workspace summary when other projects need attention.

bowline status [path] [--watch] [--workspace] [--json]

--watch: stream status frames as they change.
--workspace (alias --all): inspect the whole workspace root.

`bowline actions`

Return the safe next actions for the current status.

bowline actions [path] [--workspace] [--json]

`bowline events`

List recent workspace events.

bowline events [path] [--workspace] [--limit <n>] [--json]

--limit <n>: maximum events to return (default 50).

`bowline explain`

Explain a path's classification, access, and hydration behavior: why it syncs, hydrates, stays local, or needs review.

bowline explain <path> [--json]

`bowline search`

Search indexed project text with bounded, cursored results.

bowline search <query> [path] [--limit <n>] [--cursor <cursor>] [--path-prefix <prefix>] [--json]

--limit <n>: maximum results (default 20, max 100).
--cursor <cursor>: opaque pagination cursor in v1:<offset> form.
--path-prefix <prefix>: restrict matches to a path prefix.

`bowline symbols`

Look up indexed code symbols with bounded, cursored results.

bowline symbols <name> [path] [--limit <n>] [--cursor <cursor>] [--path-prefix <prefix>] [--json]

--limit <n>: maximum symbols (default 20, max 100).
--cursor <cursor>: opaque pagination cursor in v1:<offset> form.
--path-prefix <prefix>: restrict matches to a path prefix.

`bowline setup`

Prepare a project and report setup receipts. Runs the project's setup recipe or inferred dependency restore.

bowline setup [path] [--yes] [--json]

--yes: approve required setup changes without prompting.

`bowline prewarm`

Hydrate and prepare a project path ahead of time.

bowline prewarm <project> [--approve-setup] [--json]

--approve-setup: allow setup receipts to run when needed.

`bowline resolve`

Resolve conflicts or produce agent-ready conflict context.

bowline resolve [path] [--tui] [--copy-prompt] [--diff <conflict>] [--agent <agent>] [--accept <conflict>] [--reject <conflict>] [--json]

--tui: open the interactive resolver.
--copy-prompt: copy a repair prompt to the clipboard.
--diff <conflict>: show the diff for a specific conflict.
--agent <agent>: use a detected agent CLI (codex, claude, or cursor).
--accept <conflict> / --reject <conflict>: accept or reject a resolution.

`bowline tui`

Open the terminal workspace UI. Interactive; it has no --json mode.

bowline tui [path]

Trust

These commands manage device trust, recovery, and remote bootstrap. See device trust for the model.

`bowline devices`

List or manage local device records.

bowline devices [list|request|approve <id>|accept <id>|deny <id>|revoke <id>] [--json]

With no subcommand, devices lists devices. request raises a device approval request (accepts --root <path>).

`bowline approve`

Approve a pending device trust request. With no argument, it approves the first pending request.

bowline approve [request] [--yes] [--json] [--dry-run] [--idempotency-key <key>]

--yes: approve without an interactive prompt.

`bowline revoke`

Revoke a trusted device so it can no longer decrypt the workspace.

bowline revoke <device> [--json] [--dry-run] [--idempotency-key <key>]

`bowline recover`

Manage recovery keys and recovery-based device grants. bowline recovery is an alias.

bowline recover [status|create|verify <id>|rotate|revoke <id>|use <id>] [--json] [--dry-run] [--idempotency-key <key>]

status: show recovery key status.
create: create a new recovery key envelope.
verify <id>: verify a recovery key (reads words from stdin).
rotate: rotate recovery key material.
revoke <id>: revoke a recovery key envelope.
use <id>: use a recovery key to grant a device (reads words from stdin).

Stdin and idempotency

verify and use read sensitive Recovery Key words from stdin and reject --idempotency-key. create, rotate, and revoke accept idempotency keys.

`bowline connect`

Install Bowline on a remote host over SSH and optionally hand off to an agent. Aliased as bootstrap ssh. See connect remote hosts.

bowline connect <host> [--root <path>] [--binary <path>] [--project <p> --task <t> --agent <a>] [--json] [--dry-run] [--idempotency-key <key>]

--root <path>: workspace root for the remote host.
--binary <path>: use an alternative bowline binary.
--project, --task, --agent: start an agent lease after bootstrap (all three are required together).

Work

These commands manage work views: isolated, review-before-apply project views under ~/Code/.work.

`bowline workon`

Create or reuse a named work view for a project.

bowline workon [project] <name> [--json] [--dry-run] [--idempotency-key <key>]

`bowline work`

List work views.

bowline work [--include-hidden] [--json]

--include-hidden (alias --all): include discarded work views.

`bowline diff`

Show the diff for a work view.

bowline diff <target> [--json]

`bowline review`

Preview whether a work view is ready to accept. Defaults to the current directory.

bowline review [target] [--json]

`bowline accept`

Apply a review-ready work view to the main project.

bowline accept <target> [--json] [--dry-run] [--idempotency-key <key>]

`bowline discard`

Discard a work view.

bowline discard <target> [--json] [--dry-run] [--idempotency-key <key>]

`bowline restore`

Restore a discarded work view.

bowline restore <target> [--json] [--dry-run] [--idempotency-key <key>]

`bowline cleanup`

Preview or apply cleanup for retained work views.

bowline cleanup [--apply] [--json] [--dry-run] [--idempotency-key <key>]

--apply: apply cleanup instead of previewing it.

Agent

These commands create and drive agent leases. See the agent-native contract for the full agent surface.

`bowline agent start`

Create an agent lease and return context and prompt commands. Aliased as agent lease create.

bowline agent start [project] --task <task> [--base <base>] [--hydrate-budget <bytes>] [--work-view] [--json] [--dry-run] [--idempotency-key <key>]

--task <task>: required task description.
--base <base>: lease base (default latest-workspace, for example latest:main).
--hydrate-budget <bytes>: hydration budget (default 64MiB; accepts KiB/MiB/GiB and KB/MB/GB).
--work-view: write through an isolated work view.

`bowline agent context`

Return the full context bundle for a lease.

bowline agent context --lease <id> [--json]

`bowline agent prompt`

Return the launch prompt text for a lease.

bowline agent prompt --lease <id> [--json]

`bowline agent publish`

Publish agent output for review.

bowline agent publish --lease <id> [--json] [--dry-run] [--idempotency-key <key>]

`bowline agent complete`

Mark an agent lease complete.

bowline agent complete --lease <id> [--json] [--dry-run] [--idempotency-key <key>]

`bowline agent budget`

Grant additional hydration budget to a lease.

bowline agent budget --lease <id> --add <bytes> [--json] [--dry-run] [--idempotency-key <key>]

--add <bytes>: bytes to add (accepts KiB/MiB/GiB and KB/MB/GB).

Daemon

These commands manage the local bowline-daemon process and its OS service. See macOS and Linux for platform specifics.

`bowline daemon start` / `stop` / `status`

Start or stop the daemon process, or inspect process and service state.

bowline daemon start [--json]
bowline daemon stop [--json]
bowline daemon status [--json]

`bowline daemon install` / `restart` / `uninstall`

Install, restart, or remove the OS service for the daemon. On macOS this manages a user LaunchAgent; on Linux, a user systemd unit.

bowline daemon install [--json] [--dry-run] [--idempotency-key <key>]
bowline daemon restart [--json] [--dry-run] [--idempotency-key <key>]
bowline daemon uninstall [--json] [--dry-run] [--idempotency-key <key>]

Support

`bowline diagnostics collect`

Print a redacted diagnostics bundle for troubleshooting and support.

bowline diagnostics collect [--json]

Next steps

CLI overview: JSON output, discovery, dry-run, and idempotency conventions.
Agent-native contract: the contract agents rely on.
Status and health: interpreting status and next actions.

On this page