# Command reference (/docs/cli/commands) This is the full `bowline` command reference, grouped the same way as [`bowline help`](/docs/cli/overview). Most commands accept `--json`; mutating commands also accept `--dry-run` and, where retries are safe, `--idempotency-key `. See the [CLI overview](/docs/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 [#discovery] These commands describe the CLI itself. They're read-only and safe to run anytime. ### `bowline help` [#bowline-help] Show human or JSON help for every command. Topic help works for nested commands. ```bash bowline help [topic...] [--json] bowline help agent start --json ``` ### `bowline version` [#bowline-version] Print the CLI version and protocol compatibility. `--version` is an alias. ```bash bowline version [--json] ``` ### `bowline contract` [#bowline-contract] Print the machine-readable CLI command and output contract. `bowline schema` is an alias for discoverability. ```bash bowline contract --json bowline schema --json ``` ## Workspace [#workspace] These commands set up your workspace, report state, and explore project content. ### `bowline login` [#bowline-login] Log in and prepare the local workspace root. It observes an existing workspace without changing it, then reports state. ```bash bowline login [--root ] [--headless] [--no-poll] [--json] ``` * `--root `: 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` [#bowline-init] Initialize or observe a workspace root. With no path, it creates or inspects the default `~/Code` root. ```bash bowline init [path] [--json] ``` ### `bowline status` [#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. ```bash bowline status [path] [--watch] [--workspace] [--json] ``` * `--watch`: stream status frames as they change. * `--workspace` (alias `--all`): inspect the whole workspace root. ### `bowline actions` [#bowline-actions] Return the safe next actions for the current status. ```bash bowline actions [path] [--workspace] [--json] ``` ### `bowline events` [#bowline-events] List recent workspace events. ```bash bowline events [path] [--workspace] [--limit ] [--json] ``` * `--limit `: maximum events to return (default 50). ### `bowline explain` [#bowline-explain] Explain a path's classification, access, and hydration behavior: why it syncs, hydrates, stays local, or needs review. ```bash bowline explain [--json] ``` ### `bowline search` [#bowline-search] Search indexed project text with bounded, cursored results. ```bash bowline search [path] [--limit ] [--cursor ] [--path-prefix ] [--json] ``` * `--limit `: maximum results (default 20, max 100). * `--cursor `: opaque pagination cursor in `v1:` form. * `--path-prefix `: restrict matches to a path prefix. ### `bowline symbols` [#bowline-symbols] Look up indexed code symbols with bounded, cursored results. ```bash bowline symbols [path] [--limit ] [--cursor ] [--path-prefix ] [--json] ``` * `--limit `: maximum symbols (default 20, max 100). * `--cursor `: opaque pagination cursor in `v1:` form. * `--path-prefix `: restrict matches to a path prefix. ### `bowline setup` [#bowline-setup] Prepare a project and report setup receipts. Runs the project's [setup recipe](/docs/concepts/setup-recipes) or inferred dependency restore. ```bash bowline setup [path] [--yes] [--json] ``` * `--yes`: approve required setup changes without prompting. ### `bowline prewarm` [#bowline-prewarm] Hydrate and prepare a project path ahead of time. ```bash bowline prewarm [--approve-setup] [--json] ``` * `--approve-setup`: allow setup receipts to run when needed. ### `bowline resolve` [#bowline-resolve] Resolve [conflicts](/docs/concepts/conflicts) or produce agent-ready conflict context. ```bash bowline resolve [path] [--tui] [--copy-prompt] [--diff ] [--agent ] [--accept ] [--reject ] [--json] ``` * `--tui`: open the interactive resolver. * `--copy-prompt`: copy a repair prompt to the clipboard. * `--diff `: show the diff for a specific conflict. * `--agent `: use a detected agent CLI (`codex`, `claude`, or `cursor`). * `--accept ` / `--reject `: accept or reject a resolution. ### `bowline tui` [#bowline-tui] Open the terminal workspace UI. Interactive; it has no `--json` mode. ```bash bowline tui [path] ``` ## Trust [#trust] These commands manage device trust, recovery, and remote bootstrap. See [device trust](/docs/concepts/device-trust) for the model. ### `bowline devices` [#bowline-devices] List or manage local device records. ```bash bowline devices [list|request|approve |accept |deny |revoke ] [--json] ``` With no subcommand, `devices` lists devices. `request` raises a device approval request (accepts `--root `). ### `bowline approve` [#bowline-approve] Approve a pending device trust request. With no argument, it approves the first pending request. ```bash bowline approve [request] [--yes] [--json] [--dry-run] [--idempotency-key ] ``` * `--yes`: approve without an interactive prompt. ### `bowline revoke` [#bowline-revoke] Revoke a trusted device so it can no longer decrypt the workspace. ```bash bowline revoke [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline recover` [#bowline-recover] Manage [recovery keys](/docs/concepts/recovery) and recovery-based device grants. `bowline recovery` is an alias. ```bash bowline recover [status|create|verify |rotate|revoke |use ] [--json] [--dry-run] [--idempotency-key ] ``` * `status`: show recovery key status. * `create`: create a new recovery key envelope. * `verify `: verify a recovery key (reads words from stdin). * `rotate`: rotate recovery key material. * `revoke `: revoke a recovery key envelope. * `use `: use a recovery key to grant a device (reads words from stdin). `verify` and `use` read sensitive Recovery Key words from stdin and reject `--idempotency-key`. `create`, `rotate`, and `revoke` accept idempotency keys. ### `bowline connect` [#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](/docs/getting-started/connect-remote-hosts). ```bash bowline connect [--root ] [--binary ] [--project

--task --agent ] [--json] [--dry-run] [--idempotency-key ] ``` * `--root `: workspace root for the remote host. * `--binary `: use an alternative `bowline` binary. * `--project`, `--task`, `--agent`: start an agent lease after bootstrap (all three are required together). ## Work [#work] These commands manage [work views](/docs/concepts/work-views): isolated, review-before-apply project views under `~/Code/.work`. ### `bowline workon` [#bowline-workon] Create or reuse a named work view for a project. ```bash bowline workon [project] [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline work` [#bowline-work] List work views. ```bash bowline work [--include-hidden] [--json] ``` * `--include-hidden` (alias `--all`): include discarded work views. ### `bowline diff` [#bowline-diff] Show the diff for a work view. ```bash bowline diff [--json] ``` ### `bowline review` [#bowline-review] Preview whether a work view is ready to accept. Defaults to the current directory. ```bash bowline review [target] [--json] ``` ### `bowline accept` [#bowline-accept] Apply a review-ready work view to the main project. ```bash bowline accept [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline discard` [#bowline-discard] Discard a work view. ```bash bowline discard [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline restore` [#bowline-restore] Restore a discarded work view. ```bash bowline restore [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline cleanup` [#bowline-cleanup] Preview or apply cleanup for retained work views. ```bash bowline cleanup [--apply] [--json] [--dry-run] [--idempotency-key ] ``` * `--apply`: apply cleanup instead of previewing it. ## Agent [#agent] These commands create and drive [agent leases](/docs/concepts/agent-leases). See the [agent-native contract](/docs/agents/contract) for the full agent surface. ### `bowline agent start` [#bowline-agent-start] Create an agent lease and return context and prompt commands. Aliased as `agent lease create`. ```bash bowline agent start [project] --task [--base ] [--hydrate-budget ] [--work-view] [--json] [--dry-run] [--idempotency-key ] ``` * `--task `: required task description. * `--base `: lease base (default `latest-workspace`, for example `latest:main`). * `--hydrate-budget `: hydration budget (default 64MiB; accepts `KiB`/`MiB`/`GiB` and `KB`/`MB`/`GB`). * `--work-view`: write through an isolated [work view](/docs/concepts/work-views). ### `bowline agent context` [#bowline-agent-context] Return the full context bundle for a lease. ```bash bowline agent context --lease [--json] ``` ### `bowline agent prompt` [#bowline-agent-prompt] Return the launch prompt text for a lease. ```bash bowline agent prompt --lease [--json] ``` ### `bowline agent publish` [#bowline-agent-publish] Publish agent output for review. ```bash bowline agent publish --lease [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline agent complete` [#bowline-agent-complete] Mark an agent lease complete. ```bash bowline agent complete --lease [--json] [--dry-run] [--idempotency-key ] ``` ### `bowline agent budget` [#bowline-agent-budget] Grant additional hydration budget to a lease. ```bash bowline agent budget --lease --add [--json] [--dry-run] [--idempotency-key ] ``` * `--add `: bytes to add (accepts `KiB`/`MiB`/`GiB` and `KB`/`MB`/`GB`). ## Daemon [#daemon] These commands manage the local `bowline-daemon` process and its OS service. See [macOS](/docs/platforms/macos) and [Linux](/docs/platforms/linux) for platform specifics. ### `bowline daemon start` / `stop` / `status` [#bowline-daemon-start--stop--status] Start or stop the daemon process, or inspect process and service state. ```bash bowline daemon start [--json] bowline daemon stop [--json] bowline daemon status [--json] ``` ### `bowline daemon install` / `restart` / `uninstall` [#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. ```bash bowline daemon install [--json] [--dry-run] [--idempotency-key ] bowline daemon restart [--json] [--dry-run] [--idempotency-key ] bowline daemon uninstall [--json] [--dry-run] [--idempotency-key ] ``` ## Support [#support] ### `bowline diagnostics collect` [#bowline-diagnostics-collect] Print a redacted diagnostics bundle for troubleshooting and support. ```bash bowline diagnostics collect [--json] ``` ## Next steps [#next-steps] * [CLI overview](/docs/cli/overview): JSON output, discovery, dry-run, and idempotency conventions. * [Agent-native contract](/docs/agents/contract): the contract agents rely on. * [Status and health](/docs/concepts/status-and-health): interpreting status and next actions.