Command reference

This is the full bowline command reference, grouped the same way as bowline help. Most commands accept --json, and supported mutating commands also accept --dry-run. See the CLI overview for how those conventions work.

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 work create --json

bowline version

Print the CLI version and protocol contract.

bowline version [--json]

bowline contract

Print the machine-readable CLI command and output contract, either as a compact discovery index or as full descriptors.

bowline contract [topic...] [--summary] [--json]
bowline contract --summary --json
bowline contract work diff --json

• --summary: return the compact command discovery index instead of full descriptors.

Workspace

These commands set up your workspace and report state.

bowline login

Authenticate this machine's Bowline account session. setup is the first-run command and performs login for you; use login only to re-authenticate an already-onboarded machine.

bowline login [--headless] [--no-poll] [--json]

• --headless: run without opening a browser, for remote hosts.
• --no-poll: skip polling for authentication completion.

bowline logout

Clear the saved local account session without removing device trust.

bowline logout [--json]

• --json: return a machine-readable logout receipt.

bowline setup

Set up this machine for Bowline, or prepare one project.

bowline setup [--root <path>] [--socket <path>] [--json]
bowline setup <path> [--yes] [--socket <path>] [--json]

• --root <path>: choose the workspace root for machine setup.
• --yes: approve required project setup changes without prompting.
• --socket <path>: use a non-default daemon socket.

bowline status

Inspect workspace, sync, and attention state: conflict-aside files to reconcile, review-ready work views, pending device approvals, and degraded state. Defaults to the current project, with a compact workspace summary when other projects need attention. bowline tui shows the same attention state interactively.

bowline status [--root <path>] [--project <path>] [--watch] [--all] [--json]

• --root <path>: override the inferred workspace root.
• --project <path>: scope the view to a project or path under the root.
• --watch: stream status frames as they change.
• --all: include retained and archived work status.

bowline conflicts

List every file whose incoming version is waiting beside it, with the exact command that reconciles each one.

bowline conflicts [--root <path>] [--project <path>] [--json]

• --root <path>: override the inferred workspace root.
• --project <path>: scope the list to a project or path under the root.
• --quiet: print one aside path per line.

bowline resolve

Reconcile one conflict: keep your file, take the incoming version, or read the difference first. Exactly one of the three is required.

bowline resolve <aside-path> (--keep-local | --take-remote | --diff) [--root <path>] [--json]

• --keep-local: keep the file as it stands and discard the incoming version.
• --take-remote: replace the file with the incoming version.
• --diff: print the difference between the two and change nothing.
• --root <path>: override the inferred workspace root.

bowline deletions

Sync refuses to publish a removal batch far larger than any ordinary edit produces, and publishes nothing at all until you agree it is real. This command shows what would be deleted on every device, and confirms it.

bowline deletions [--confirm] [--socket <path>] [--json] [--dry-run]

• --confirm: authorise the refused deletion. It applies to one push only; a later oversized batch is refused again.

Without --confirm the command only reports. If the deletions were not intended, restore the files instead and sync resumes on its own.

bowline events

List recent workspace events.

bowline events [--root <path>] [--project <path>] [--limit <n>] [--json]

• --root <path>: override the inferred workspace root.
• --project <path>: scope events to a project or path under the root.
• --limit <n>: maximum events to return (default 50).

bowline tui

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

bowline tui [--root <path>] [--project <path>] [--socket <path>]

• --root <path>: override the inferred workspace root.
• --project <path>: open the view for a project or path under the root.
• --socket <path>: use a non-default daemon socket.

bowline forget-local

Remove one materialized project from this device after previewing the change.

bowline forget-local <project> [--yes] [--json] [--dry-run]

• --yes: remove local bytes after reviewing the preview.
• --json: return a machine-readable lifecycle receipt.
• --dry-run: preview the local bytes that would be removed.

bowline archive

Hide a project from default namespace views without deleting local bytes, or restore an archived project.

bowline archive <project> [--restore] [--json] [--dry-run]

• --restore: restore the archived project to active namespace views.
• --json: return a machine-readable lifecycle receipt.
• --dry-run: preview the archive or restore transition.

bowline purge

Schedule remote destruction for an archived project after a grace period, or cancel a pending purge.

bowline purge <project> [--grace <days> | --cancel] [--json] [--dry-run]

• --grace <days>: set a grace period from 1 to 90 days.
• --cancel: cancel a pending purge and leave the project archived.
• --json: return a machine-readable lifecycle receipt.
• --dry-run: preview the remote-retention impact.

Trust

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

bowline device list

List or manage local device records.

bowline device list [--root <path>] [--json]
bowline device request [--root <path>] [--json]
bowline device accept [--root <path>] --request <id> [--json]

device list lists devices, device request raises a device approval request, and device accept accepts an encrypted grant created for this requesting device.

bowline device approve

Approve a pending device trust request.

bowline device approve [--root <path>] (--request <id> | --code <matching-code>) [--yes] [--json] [--dry-run]

• --request <id>: approve a specific pending request.
• --code <matching-code>: approve the pending request with this matching code.
• --yes: approve without an interactive prompt.

bowline device deny

Deny a pending device trust request.

bowline device deny [--root <path>] (--request <id> | --code <matching-code>) [--json] [--dry-run]

bowline device revoke

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

bowline device revoke [--root <path>] --device <id> [--json] [--dry-run]

bowline recover

Manage recovery keys and recovery-based device grants. recover is the only command name.

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

• 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).

Remote

This command installs Bowline on a machine you own and brings it into device trust. Once the host is trusted, it has the same real ~/Code; running an agent there is your own step, with your own tools.

bowline connect

Install Bowline on a remote host over SSH and complete device trust. See connect remote hosts.

bowline connect <host> [--root <path>] [--binary <path>] [--json] [--dry-run]

• --root <path>: workspace root for the remote host.
• --binary <path>: use a local bowline binary artifact for the remote install.

Work

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

bowline work create

Create or reuse a named work view for a project.

bowline work create [project] <name> [--from <restore-point>] [--json] [--dry-run]

• --from <restore-point>: use a restore point or snapshot as the work-view base.

bowline work list

List work views.

bowline work list [--all] [--json]

• --all: include hidden and retained work views.

bowline work diff

Show the diff for a work view.

bowline work diff [target] [--path <glob>...] [--json]

• --path <glob>: limit the diff to matching project-relative paths; repeat the flag to include multiple patterns.

bowline work review

Preview whether a work view is ready to accept.

bowline work review <target> [--path <glob>...] [--json]

• --path <glob>: limit the review to matching project-relative paths; repeat the flag to include multiple patterns.

bowline work accept

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

bowline work accept <target> [--path <glob>...] [--json] [--dry-run]

• --path <glob>: apply only matching project-relative paths; repeat the flag to include multiple patterns.

bowline work discard

Discard a work view.

bowline work discard <target> [--json] [--dry-run]

bowline work restore

Restore a discarded work view.

bowline work restore <target> [--json] [--dry-run]

bowline work cleanup

Preview or apply cleanup for retained work views.

bowline work cleanup [--apply] [--json] [--dry-run]

• --apply: apply cleanup instead of previewing it.

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]
bowline daemon restart [--json] [--dry-run]
bowline daemon uninstall [--json] [--dry-run]

Support

bowline diagnostics collect

Print a redacted diagnostics bundle for troubleshooting and support.

bowline diagnostics collect --root <path> [--json]

• --root <path>: select the workspace root to collect from.
• --json: return the redacted diagnostics bundle as machine-readable output.

bowline doctor

Run read-only engine diagnostics with redacted, fixed reason codes. Reach for this when sync looks stuck or degraded and you want a structured answer instead of log spelunking.

bowline doctor [--engine manifest] [--json]

• --engine <name>: select the engine to diagnose (default: manifest).
• --json: return the diagnostic report as machine-readable output.

Next steps

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