CLI overview

For both humans and coding agents, the bowline CLI is the primary surface for inspecting, repairing, and deciding. It's a thin client over the local bowline-daemon, which owns sync, hydration, and merging. This page covers how the CLI is organized and the conventions that apply across every command. For every command and flag, see the command reference.

How the CLI talks to the daemon

The CLI sends requests to the local daemon over a Unix domain socket. The default socket path is /tmp/bowline-daemon.sock. You rarely need to think about this, but two things are worth knowing:

• --socket <path> points the CLI at a non-default socket. The path is part of a command's identity for idempotency, so reuse the same socket when replaying a mutation.
• If commands report the daemon is unreachable, check it with bowline daemon status and start or install it with bowline daemon start or bowline daemon install.

Command groups

The command surface is grouped by intent. The reference page is organized the same way.

Global flags

These flags apply across commands.

JSON output

Every command except the interactive TUI accepts --json for scripting and automation. JSON mode is stable and contract-backed, the right choice for agents and scripts.

When a command fails in JSON mode, it prints a CommandErrorOutput envelope to stdout and exits non-zero. The envelope includes contractVersion, command, generatedAt, status, and an optional top-level nextActions field, plus an error object. The error object holds code, message, and recoverability, with optional remediation, details, retryAfterSeconds, and correlationId. Human-mode failures print to stderr instead.

Discovery

The CLI is self-describing, so agents and scripts don't have to scrape prose. Three commands cover discovery:

bowline contract --json
bowline help --json
bowline status --root ~/Code --json

bowline contract --json is canonical and lists the CLI version, protocol version, every command descriptor (group, usage, options, examples, JSON output type, side-effect level, and support for --json, --dry-run, and --idempotency-key), and fixture paths. Topic help works in JSON:

bowline help agent start --json
bowline daemon install --help --json

Bounded exploration

Exploration commands return bounded, cursored results so output stays predictable. bowline search and bowline symbols default to a limit of 20, reject limits above 100, and accept opaque cursors in v1:<offset> form. They emit nextCursor while more results exist within the accepted window.

bowline search "auth callback" ~/Code/acme/web --limit 20 --json
bowline search "auth callback" ~/Code/acme/web --cursor v1:20 --json

Dry-run and idempotency

Mutating commands that an agent might retry support --dry-run and --idempotency-key, so automation can preview and safely retry.

• --dry-run returns a preview and changes no filesystem, metadata, daemon, trust, recovery, or lease state. Its result includes the exact command to apply the change.
• --idempotency-key <key> makes a non-dry-run mutation replay-safe. Replaying the same key with the same normalized request returns the stored result marked replayed: true. The request identity includes the working directory for relative targets and target-affecting globals such as --socket. Reusing a key with a different request returns an idempotency_conflict error.

Next steps

• Command reference: every command, flag, and example.
• Agent-native contract: drive Bowline from a coding agent.
• Status and health: read status output and next actions.