# CLI overview (/docs/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](/docs/cli/commands).

## How the CLI talks to the daemon [#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 [#command-groups]

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

| Group     | Purpose                                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| Discovery | `help`, `version`, `contract`.                                                                                        |
| Workspace | `login`, `init`, `status`, `actions`, `events`, `explain`, `search`, `symbols`, `setup`, `prewarm`, `resolve`, `tui`. |
| Trust     | `devices`, `approve`, `revoke`, `recover`, `connect`.                                                                 |
| Work      | `workon`, `work`, `diff`, `review`, `accept`, `discard`, `restore`, `cleanup`.                                        |
| Agent     | `agent start`, `agent context`, `agent prompt`, `agent publish`, `agent complete`, `agent budget`.                    |
| Daemon    | `daemon start`, `daemon stop`, `daemon status`, `daemon install`, `daemon restart`, `daemon uninstall`.               |
| Support   | `diagnostics collect`.                                                                                                |

## Global flags [#global-flags]

These flags apply across commands.

| Flag                      | Applies to          | Description                              |
| ------------------------- | ------------------- | ---------------------------------------- |
| `--json`                  | Most commands       | Emit machine-readable JSON on stdout.    |
| `--socket <path>`         | All commands        | Use a non-default daemon socket.         |
| `--dry-run`               | Mutating commands   | Preview a change without applying it.    |
| `--idempotency-key <key>` | Retryable mutations | Make a non-dry-run mutation replay-safe. |

## JSON output [#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 [#discovery]

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

```bash title="Terminal"
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:

```bash title="Terminal"
bowline help agent start --json
bowline daemon install --help --json
```

## Bounded exploration [#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.

```bash title="Terminal"
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 [#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.

<Callout type="warn" title="Recovery and idempotency">
  Recovery `verify` and `use` read sensitive Recovery Key words from stdin and
  reject idempotency keys, so submitted words are never persisted or replayed
  without validation. Recovery `create`, `rotate`, and `revoke` accept keys.
</Callout>

## Next steps [#next-steps]

* [Command reference](/docs/cli/commands): every command, flag, and example.
* [Agent-native contract](/docs/agents/contract): drive Bowline from a coding
  agent.
* [Status and health](/docs/concepts/status-and-health): read status output and
  next actions.