# Command-Line Help for `devboy`

> Auto-generated by `devboy docs cli` from the live `clap` definition. Do not edit by hand — re-run the command (or `cargo test --workspace` will fail with a drift error) to refresh.

This document contains the help content for the `devboy` command-line program.

**Command Overview:**

* [`devboy`↴](#devboy)
* [`devboy init`↴](#devboy-init)
* [`devboy mcp`↴](#devboy-mcp)
* [`devboy config`↴](#devboy-config)
* [`devboy config set`↴](#devboy-config-set)
* [`devboy config set-secret`↴](#devboy-config-set-secret)
* [`devboy config get`↴](#devboy-config-get)
* [`devboy config list`↴](#devboy-config-list)
* [`devboy config path`↴](#devboy-config-path)
* [`devboy context`↴](#devboy-context)
* [`devboy context list`↴](#devboy-context-list)
* [`devboy context use`↴](#devboy-context-use)
* [`devboy issues`↴](#devboy-issues)
* [`devboy mrs`↴](#devboy-mrs)
* [`devboy test`↴](#devboy-test)
* [`devboy proxy`↴](#devboy-proxy)
* [`devboy proxy add`↴](#devboy-proxy-add)
* [`devboy proxy remove`↴](#devboy-proxy-remove)
* [`devboy proxy tools`↴](#devboy-proxy-tools)
* [`devboy proxy call`↴](#devboy-proxy-call)
* [`devboy proxy status`↴](#devboy-proxy-status)
* [`devboy tools`↴](#devboy-tools)
* [`devboy tools list`↴](#devboy-tools-list)
* [`devboy tools disable`↴](#devboy-tools-disable)
* [`devboy tools enable`↴](#devboy-tools-enable)
* [`devboy tools reset`↴](#devboy-tools-reset)
* [`devboy tools call`↴](#devboy-tools-call)
* [`devboy tools docs`↴](#devboy-tools-docs)
* [`devboy docs`↴](#devboy-docs)
* [`devboy docs cli`↴](#devboy-docs-cli)
* [`devboy skills`↴](#devboy-skills)
* [`devboy skills list`↴](#devboy-skills-list)
* [`devboy skills show`↴](#devboy-skills-show)
* [`devboy skills install`↴](#devboy-skills-install)
* [`devboy skills upgrade`↴](#devboy-skills-upgrade)
* [`devboy skills remove`↴](#devboy-skills-remove)
* [`devboy agents`↴](#devboy-agents)
* [`devboy agents list`↴](#devboy-agents-list)
* [`devboy onboard`↴](#devboy-onboard)
* [`devboy secrets`↴](#devboy-secrets)
* [`devboy secrets list`↴](#devboy-secrets-list)
* [`devboy secrets describe`↴](#devboy-secrets-describe)
* [`devboy secrets validate`↴](#devboy-secrets-validate)
* [`devboy secrets migrate`↴](#devboy-secrets-migrate)
* [`devboy secrets agent`↴](#devboy-secrets-agent)
* [`devboy secrets agent status`↴](#devboy-secrets-agent-status)
* [`devboy secrets agent start`↴](#devboy-secrets-agent-start)
* [`devboy secrets agent install`↴](#devboy-secrets-agent-install)
* [`devboy secrets agent uninstall`↴](#devboy-secrets-agent-uninstall)
* [`devboy secrets ui`↴](#devboy-secrets-ui)
* [`devboy secrets rotate`↴](#devboy-secrets-rotate)
* [`devboy secrets catalog`↴](#devboy-secrets-catalog)
* [`devboy secrets catalog list`↴](#devboy-secrets-catalog-list)
* [`devboy secrets catalog status`↴](#devboy-secrets-catalog-status)
* [`devboy secrets catalog add-url`↴](#devboy-secrets-catalog-add-url)
* [`devboy secrets catalog refresh`↴](#devboy-secrets-catalog-refresh)
* [`devboy secrets catalog forget`↴](#devboy-secrets-catalog-forget)
* [`devboy secrets catalog pin`↴](#devboy-secrets-catalog-pin)
* [`devboy secrets catalog validate`↴](#devboy-secrets-catalog-validate)
* [`devboy secrets setup`↴](#devboy-secrets-setup)
* [`devboy secrets kdbx`↴](#devboy-secrets-kdbx)
* [`devboy secrets kdbx peek`↴](#devboy-secrets-kdbx-peek)
* [`devboy secrets kdbx describe-metadata`↴](#devboy-secrets-kdbx-describe-metadata)
* [`devboy secrets kdbx edit-metadata`↴](#devboy-secrets-kdbx-edit-metadata)
* [`devboy hooks`↴](#devboy-hooks)
* [`devboy hooks install`↴](#devboy-hooks-install)
* [`devboy hooks check`↴](#devboy-hooks-check)
* [`devboy hooks check secret-alias`↴](#devboy-hooks-check-secret-alias)
* [`devboy trace`↴](#devboy-trace)
* [`devboy trace begin`↴](#devboy-trace-begin)
* [`devboy trace event`↴](#devboy-trace-event)
* [`devboy trace end`↴](#devboy-trace-end)
* [`devboy doctor`↴](#devboy-doctor)
* [`devboy upgrade`↴](#devboy-upgrade)
* [`devboy benchmark`↴](#devboy-benchmark)
* [`devboy format-pipeline`↴](#devboy-format-pipeline)

## `devboy`

DevBoy - AI-powered development tools

**Usage:** `devboy [OPTIONS] [COMMAND]`

###### **Subcommands:**

* `init` — Initialize a new .devboy.toml configuration file
* `mcp` — Start the MCP server (stdio mode for AI assistants)
* `config` — Configuration management
* `context` — Context (profile) management
* `issues` — Get information about issues
* `mrs` — Get information about merge requests / pull requests
* `test` — Test provider connection
* `proxy` — Interact with upstream MCP proxy servers
* `tools` — Manage built-in tools (enable/disable). Interactive mode when run without subcommand
* `docs` — Generate reference documentation from the live binary (built-in tools or CLI surface)
* `skills` — Manage skills — procedural recipes installed alongside the tool bundle
* `agents` — Inspect AI coding agents installed on this machine
* `onboard` — First-run setup: detect your AI agent and install the right skills bundle
* `secrets` — Discover and inspect declared secrets (metadata only — values are never shown)
* `hooks` — Manage git hooks installed by devboy (e.g. the secret-alias pre-commit lint, ADR-020 §5)
* `trace` — Write to a skill's self-feedback session trace (ADR-015)
* `doctor` — Run diagnostic checks for the local DevBoy setup
* `upgrade` — Upgrade devboy to the latest version
* `benchmark` — Benchmark format pipeline on real open-source project data (JSON vs TOON)
* `format-pipeline` — Format JSON from stdin through the TOON pipeline (pipe mode)

###### **Options:**

* `-v`, `--verbose` — Enable verbose output
* `--ci` — Force CI routing mode for the whole invocation. Equivalent to setting `DEVBOY_CI=1`. CI mode promotes the env-store source to the front of the chain, skips `NotInstalled` sources silently, and refuses interactive unlock prompts (local-vault PIN, biometric). See ADR-021 §8



## `devboy init`

Initialize a new .devboy.toml configuration file

**Usage:** `devboy init [OPTIONS]`

###### **Options:**

* `-y`, `--yes` — Skip prompts and use defaults (required in non-TTY environments)
* `--dry-run` — Show what would be done without making changes
* `-f`, `--force` — Overwrite existing config (creates timestamped backup)
* `--claude` — Register devboy as MCP server in Claude Code
* `--kimi` — Register devboy as MCP server in Kimi CLI
* `--codex-cli` — Register devboy as MCP server in Codex CLI
* `--copilot` — Register devboy as MCP server in Copilot CLI
* `--gemini` — Register devboy as MCP server in Gemini CLI
* `--opencode` — Register devboy as MCP server in OpenCode
* `--forge` — Register devboy as MCP server in ForgeCode
* `-c`, `--context <CONTEXT>` — Context name for the configuration
* `--proxy <PROXY>` — Add MCP proxy server URL
* `--proxy-only` — Only configure proxy, skip git remote auto-detection
* `--proxy-name <PROXY_NAME>` — Proxy server name (default: "proxy")
* `--proxy-transport <PROXY_TRANSPORT>` — Proxy transport type (default: streamable-http)

  Possible values:
  - `streamable-http`:
    Modern HTTP POST-based transport with mcp-session-id header
  - `sse`:
    Legacy MCP transport using GET for SSE stream, POST for requests

* `--proxy-token-key <PROXY_TOKEN_KEY>` — Keychain key for proxy token (e.g., "proxy.token")
* `--proxy-token <PROXY_TOKEN>` — Proxy token value (will be stored in keychain automatically)
* `--proxy-auth-type <PROXY_AUTH_TYPE>` — Proxy auth type (default: bearer if token provided, else none)

  Possible values:
  - `bearer`:
    Bearer token authentication
  - `api_key`:
    API key authentication
  - `none`:
    No authentication

* `--remote-config-url <REMOTE_CONFIG_URL>` — Remote config URL (fetched on startup, TOML response merged with local config)
* `--remote-config-token <REMOTE_CONFIG_TOKEN>` — Bearer token for remote config endpoint
* `--detect-git` — Force git remote auto-detection even when `--remote-config-url` is set.

   By default, passing `--remote-config-url` suppresses local git auto-detection (remote config is treated as the source of truth for integrations). Use `--detect-git` to restore the pre-existing behaviour and auto-add a local GitHub/GitLab context alongside the remote config.



## `devboy mcp`

Start the MCP server (stdio mode for AI assistants)

**Usage:** `devboy mcp [OPTIONS]`

###### **Options:**

* `--no-config` — Skip loading config file, use only environment variables



## `devboy config`

Configuration management

**Usage:** `devboy config <COMMAND>`

###### **Subcommands:**

* `set` — Set a configuration value
* `set-secret` — Set a secret value (stored in OS keychain)
* `get` — Get a configuration value
* `list` — List all configuration
* `path` — Show configuration file path



## `devboy config set`

Set a configuration value

**Usage:** `devboy config set <KEY> <VALUE>`

###### **Arguments:**

* `<KEY>` — Config key (e.g., github.owner, gitlab.url)
* `<VALUE>` — Config value. `allow_hyphen_values` handles the common case of negative numbers like `-1` — clap no longer treats them as flags but passes them to the domain validator which returns a clear validation error



## `devboy config set-secret`

Set a secret value (stored in OS keychain)

**Usage:** `devboy config set-secret <KEY> <VALUE>`

###### **Arguments:**

* `<KEY>` — Secret key (e.g., github.token, gitlab.token)
* `<VALUE>` — Secret value (will be stored securely)



## `devboy config get`

Get a configuration value

**Usage:** `devboy config get <KEY>`

###### **Arguments:**

* `<KEY>` — Config key (e.g., github.owner, gitlab.url)



## `devboy config list`

List all configuration

**Usage:** `devboy config list`



## `devboy config path`

Show configuration file path

**Usage:** `devboy config path`



## `devboy context`

Context (profile) management

**Usage:** `devboy context <COMMAND>`

###### **Subcommands:**

* `list` — List available contexts and show active one
* `use` — Switch active context



## `devboy context list`

List available contexts and show active one

**Usage:** `devboy context list`



## `devboy context use`

Switch active context

**Usage:** `devboy context use <NAME>`

###### **Arguments:**

* `<NAME>`



## `devboy issues`

Get information about issues

**Usage:** `devboy issues [OPTIONS]`

###### **Options:**

* `-s`, `--state <STATE>` — Filter by state

  Default value: `open`

  Possible values: `open`, `closed`, `all`

* `-l`, `--limit <LIMIT>` — Maximum number of issues to display

  Default value: `20`



## `devboy mrs`

Get information about merge requests / pull requests

**Usage:** `devboy mrs [OPTIONS]`

###### **Options:**

* `-s`, `--state <STATE>` — Filter by state

  Default value: `open`

  Possible values: `open`, `merged`, `closed`, `all`

* `-l`, `--limit <LIMIT>` — Maximum number of MRs to display

  Default value: `20`



## `devboy test`

Test provider connection

**Usage:** `devboy test <PROVIDER>`

###### **Arguments:**

* `<PROVIDER>` — Provider to test (github, gitlab, clickup, jira, slack)



## `devboy proxy`

Interact with upstream MCP proxy servers

**Usage:** `devboy proxy <COMMAND>`

###### **Subcommands:**

* `add` — Add a new proxy server configuration
* `remove` — Remove a proxy server configuration
* `tools` — List available tools from all upstream proxy servers
* `call` — Call a tool on an upstream proxy server
* `status` — Inspect transparent-routing status: matched tools, overrides, schema issues



## `devboy proxy add`

Add a new proxy server configuration

**Usage:** `devboy proxy add [OPTIONS] --url <URL> <NAME>`

###### **Arguments:**

* `<NAME>` — Proxy server name

###### **Options:**

* `--url <URL>` — Proxy server URL
* `--transport <TRANSPORT>` — Transport type (default: streamable-http)

  Default value: `streamable-http`

  Possible values:
  - `streamable-http`:
    Modern HTTP POST-based transport with mcp-session-id header
  - `sse`:
    Legacy MCP transport using GET for SSE stream, POST for requests

* `--token-key <TOKEN_KEY>` — Keychain key for proxy token (e.g., "proxy.token")
* `--token <TOKEN>` — Token value (will be stored in keychain automatically)
* `--auth-type <AUTH_TYPE>` — Auth type (default: bearer if token provided, else none)

  Possible values:
  - `bearer`:
    Bearer token authentication
  - `api_key`:
    API key authentication
  - `none`:
    No authentication

* `-f`, `--force` — Overwrite existing proxy with same name



## `devboy proxy remove`

Remove a proxy server configuration

**Usage:** `devboy proxy remove <NAME>`

###### **Arguments:**

* `<NAME>` — Proxy server name to remove



## `devboy proxy tools`

List available tools from all upstream proxy servers

**Usage:** `devboy proxy tools [OPTIONS]`

###### **Options:**

* `--descriptions` — Show tool descriptions



## `devboy proxy call`

Call a tool on an upstream proxy server

**Usage:** `devboy proxy call <TOOL> [ARGS]`

###### **Arguments:**

* `<TOOL>` — Tool name (e.g., devboy-cloud__get_issues)
* `<ARGS>` — JSON arguments (optional)

  Default value: `{}`



## `devboy proxy status`

Inspect transparent-routing status: matched tools, overrides, schema issues

**Usage:** `devboy proxy status [OPTIONS]`

###### **Options:**

* `--json` — Output as JSON instead of a human-readable report



## `devboy tools`

Manage built-in tools (enable/disable). Interactive mode when run without subcommand

**Usage:** `devboy tools [COMMAND]`

###### **Subcommands:**

* `list` — List all built-in tools and their status (enabled/disabled)
* `disable` — Disable specific built-in tools
* `enable` — Enable specific built-in tools (remove from disabled list)
* `reset` — Reset all built-in tools filtering (re-enable everything)
* `call` — Call a built-in tool directly
* `docs` — Generate auto-built reference docs for built-in tools



## `devboy tools list`

List all built-in tools and their status (enabled/disabled)

**Usage:** `devboy tools list`



## `devboy tools disable`

Disable specific built-in tools

**Usage:** `devboy tools disable <NAMES>...`

###### **Arguments:**

* `<NAMES>` — Tool names to disable



## `devboy tools enable`

Enable specific built-in tools (remove from disabled list)

**Usage:** `devboy tools enable <NAMES>...`

###### **Arguments:**

* `<NAMES>` — Tool names to enable



## `devboy tools reset`

Reset all built-in tools filtering (re-enable everything)

**Usage:** `devboy tools reset`



## `devboy tools call`

Call a built-in tool directly

**Usage:** `devboy tools call <NAME> [ARGS]`

###### **Arguments:**

* `<NAME>` — Tool name (e.g., get_issues, list_contexts)
* `<ARGS>` — JSON arguments (optional)

  Default value: `{}`



## `devboy tools docs`

Generate auto-built reference docs for built-in tools

**Usage:** `devboy tools docs [OPTIONS]`

###### **Options:**

* `--format <FORMAT>` — Output format

  Default value: `markdown`

  Possible values: `markdown`, `json`

* `--output <OUTPUT>` — Write to a file instead of stdout
* `--check` — Compare the rendered docs to an existing file and exit non-zero if they differ. Useful in CI: `--check --output docs/guide/reference/tools.md`



## `devboy docs`

Generate reference documentation from the live binary (built-in tools or CLI surface)

**Usage:** `devboy docs <COMMAND>`

###### **Subcommands:**

* `cli` — Render reference docs for every CLI subcommand and flag



## `devboy docs cli`

Render reference docs for every CLI subcommand and flag.

Sourced from the live `clap` definition — no separate maintenance. In CI, pair with `--check --output docs/guide/reference/cli.md` to fail when the committed snapshot drifts from the binary.

**Usage:** `devboy docs cli [OPTIONS]`

###### **Options:**

* `--format <FORMAT>` — Output format (only `markdown` is supported in v1; `json` is reserved for a future structured walk over `Cli::command()`)

  Default value: `markdown`

  Possible values: `markdown`

* `--output <OUTPUT>` — Write to a file instead of stdout
* `--check` — Compare the rendered docs against `--output` and exit non-zero on drift. Use in CI / pre-commit hooks



## `devboy skills`

Manage skills — procedural recipes installed alongside the tool bundle

**Usage:** `devboy skills <COMMAND>`

###### **Subcommands:**

* `list` — List every skill the embedded source knows about
* `show` — Print a skill's full `SKILL.md` contents
* `install` — Install one or more skills to the resolved target(s)
* `upgrade` — Upgrade previously installed skills (shortcut for `install` on what the manifest already knows)
* `remove` — Remove installed skills from the resolved target(s)



## `devboy skills list`

List every skill the embedded source knows about

**Usage:** `devboy skills list [OPTIONS]`

###### **Options:**

* `--category <CATEGORY>` — Filter by category id (e.g. `self-bootstrap`, `issue-tracking`)



## `devboy skills show`

Print a skill's full `SKILL.md` contents

**Usage:** `devboy skills show <NAME>`

###### **Arguments:**

* `<NAME>` — Skill name



## `devboy skills install`

Install one or more skills to the resolved target(s)

**Usage:** `devboy skills install [OPTIONS] [NAMES]...`

###### **Arguments:**

* `<NAMES>` — Skill names. Ignored when `--all` or `--category` is used

###### **Options:**

* `--all` — Install every skill the embedded source knows about
* `--category <CATEGORY>` — Install every skill in the given category
* `--global` — Install globally at `~/.agents/skills/` instead of repo-local
* `--local` — When combined with `--agent`, install under the repo instead of the user home
* `--agent <AGENTS>` — Install for one or more agents (claude, codex, cursor, kimi, all). Accepts the value repeatedly or comma-delimited
* `--force` — Overwrite user-modified files
* `--dry-run` — Show what would happen without touching the filesystem



## `devboy skills upgrade`

Upgrade previously installed skills (shortcut for `install` on what the manifest already knows)

**Usage:** `devboy skills upgrade [OPTIONS] [NAMES]...`

###### **Arguments:**

* `<NAMES>` — Upgrade only these skills (default: every skill in the manifest)

###### **Options:**

* `--global` — Upgrade the global target at `~/.agents/skills/`
* `--local` — When combined with `--agent`, upgrade under the repo instead of the user home
* `--agent <AGENTS>` — Apply to these agents' install paths
* `--force` — Overwrite user-modified files
* `--dry-run` — Show what would happen without touching the filesystem



## `devboy skills remove`

Remove installed skills from the resolved target(s)

**Usage:** `devboy skills remove [OPTIONS] <NAMES>...`

###### **Arguments:**

* `<NAMES>` — Skill names to remove

###### **Options:**

* `--global` — Counterpart to `--agent` (see `install`)
* `--local` — Counterpart to `--agent` (see `install`)
* `--agent <AGENTS>` — Apply to these agents' install paths
* `--strict` — Fail if a requested skill is not present at the target
* `--dry-run` — Show what would happen without touching the filesystem



## `devboy agents`

Inspect AI coding agents installed on this machine

**Usage:** `devboy agents <COMMAND>`

###### **Subcommands:**

* `list` — List detected AI coding agents with status, session count, and last-used time



## `devboy agents list`

List detected AI coding agents with status, session count, and last-used time

**Usage:** `devboy agents list [OPTIONS]`

###### **Options:**

* `--format <FORMAT>` — Output format

  Default value: `table`

  Possible values: `table`, `json`




## `devboy onboard`

First-run setup: detect your AI agent and install the right skills bundle

**Usage:** `devboy onboard [OPTIONS]`

###### **Options:**

* `--agent <AGENT>` — Override the auto-detected primary agent (e.g. `--agent claude`)
* `--profile <PROFILE>` — Skill bundle profile to install (default: dev)

  Default value: `dev`
* `-y`, `--yes` — Skip confirmation — install without asking. Required in non-TTY
* `--dry-run` — Show the plan without writing anything



## `devboy secrets`

Discover and inspect declared secrets (metadata only — values are never shown)

**Usage:** `devboy secrets <COMMAND>`

###### **Subcommands:**

* `list` — List every path the active project's manifest declares, merged with the global index. Values are never shown
* `describe` — Print the resolved metadata card for a single secret path
* `validate` — Validate manifest paths' format / liveness as a CI gate. Format-only by default; pass `--liveness` to also probe upstreams (github + gitlab). See ADR-021 §6
* `migrate` — Move a legacy keychain entry under the ADR-020 path convention. See `doctor` "Legacy keychain entries" (P10.1) for what's eligible
* `agent` — Manage the local secret-store agent daemon (ADR-023 §3.3)
* `ui` — Open the native UI (TUI in a terminal, GUI in a window). Backend autodetected from `$DISPLAY` / `$WAYLAND_DISPLAY` on Linux and the OS on macOS / Windows; override with `--tui` or `--gui`. See ADR-023 §3.4
* `rotate` — Rotate a secret: open the provider URL in the browser, destructive-confirm, read the new value, format-validate, and record `last_rotated_at`. See ADR-023 §3.4
* `catalog` — Manage the token catalog (provider procedure files the `secrets ui` form binds to). See ADR-023 §3.4
* `setup` — Run the setup-secrets wizard against the current directory. Default mode is `--scan-only` — read-only preview of what the wizard would propose. Pass `--write-manifest` to commit the proposals to `<repo>/.devboy/secrets.toml`. See ADR-023 §3.8 and `crates/devboy-skills/skills/00-self-bootstrap/setup-secrets/`
* `kdbx` — Work with KDBX 4 (KeePass) files as a SecretSource. The passphrase is prompted from stdin with no echo; the decrypted body lives only inside this process and is dropped on exit. See ADR-021 §8 + `crates/plugins/secrets/kdbx/`



## `devboy secrets list`

List every path the active project's manifest declares, merged with the global index. Values are never shown

**Usage:** `devboy secrets list [OPTIONS]`

###### **Options:**

* `--internal` — Include framework-internal paths (`__*`) in the output. Hidden by default per ADR-021 §5
* `--json` — Print as JSON instead of a human-readable table



## `devboy secrets describe`

Print the resolved metadata card for a single secret path

**Usage:** `devboy secrets describe [OPTIONS] <PATH>`

###### **Arguments:**

* `<PATH>` — The secret path (e.g. `team/gitlab/token-deploy`)

###### **Options:**

* `--json` — Print as JSON instead of a human-readable card



## `devboy secrets validate`

Validate manifest paths' format / liveness as a CI gate. Format-only by default; pass `--liveness` to also probe upstreams (github + gitlab). See ADR-021 §6

**Usage:** `devboy secrets validate [OPTIONS] [PATH]`

###### **Arguments:**

* `<PATH>` — Validate just one path. Defaults to all manifest paths

###### **Options:**

* `--format-only` — Format check only — skip the upstream liveness probe. This is the implied default; pass `--format-only` to be explicit (e.g. when `--liveness` is set in a CI variable you want to override locally)
* `--liveness` — Run upstream liveness probes (github, gitlab) in addition to the format check
* `--all` — Print every path, including ones that pass cleanly. By default the command shows only failures, warnings, and skipped rows
* `--json` — Print as JSON (one object per path) instead of a human-readable table



## `devboy secrets migrate`

Move a legacy keychain entry under the ADR-020 path convention. See `doctor` "Legacy keychain entries" (P10.1) for what's eligible

**Usage:** `devboy secrets migrate [OPTIONS] [LEGACY_KEY]`

###### **Arguments:**

* `<LEGACY_KEY>` — Legacy keychain key to migrate (e.g. `github/token`). Required unless `--all` is set

###### **Options:**

* `--all` — Migrate every present legacy entry in one go. Uses the suggested target path for each; pass `--keep-legacy` to also retain the source rows (the default in batch mode)
* `--target <TARGET>` — Pre-supply the target path; bypasses the interactive prompt for the single-entry flow
* `--keep-legacy` — Don't delete the legacy entry after a successful write. Defaults to `true` in `--all` mode (cautious)
* `--dry-run` — Print the plan without writing anything
* `-y`, `--yes` — Skip the prompts entirely. Equivalent to `--target <suggested>` and not deleting unless `--no-keep-legacy` is set



## `devboy secrets agent`

Manage the local secret-store agent daemon (ADR-023 §3.3)

**Usage:** `devboy secrets agent <COMMAND>`

###### **Subcommands:**

* `status` — Report the agent socket path and whether the daemon is currently accepting connections
* `start` — Spawn the agent if it isn't already running. Idempotent — no-op when the socket is already live
* `install` — Install a per-user service unit so the daemon starts at login and respawns on failure. macOS writes a launchd plist at `~/Library/LaunchAgents/dev.devboy.secrets.plist`; Linux writes a systemd-user unit at `~/.config/systemd/user/devboy-secrets-agent.service`. After install: verify with `launchctl print gui/$(id -u)/dev.devboy.secrets` (macOS) or `systemctl --user status devboy-secrets-agent.service` (Linux)
* `uninstall` — Stop the user service (if loaded) and remove the unit file written by `install`. Idempotent — running it twice is fine



## `devboy secrets agent status`

Report the agent socket path and whether the daemon is currently accepting connections

**Usage:** `devboy secrets agent status`



## `devboy secrets agent start`

Spawn the agent if it isn't already running. Idempotent — no-op when the socket is already live

**Usage:** `devboy secrets agent start [OPTIONS]`

###### **Options:**

* `--vault <VAULT>` — Override the vault file the daemon will operate on. Defaults to `<config_dir>/devboy-tools/secrets/vault.dvb`
* `--timeout-secs <TIMEOUT_SECS>` — Cap on the wait-for-socket loop, in seconds. Defaults to [`secrets_agent::DEFAULT_SPAWN_TIMEOUT`]



## `devboy secrets agent install`

Install a per-user service unit so the daemon starts at login and respawns on failure. macOS writes a launchd plist at `~/Library/LaunchAgents/dev.devboy.secrets.plist`; Linux writes a systemd-user unit at `~/.config/systemd/user/devboy-secrets-agent.service`. After install: verify with `launchctl print gui/$(id -u)/dev.devboy.secrets` (macOS) or `systemctl --user status devboy-secrets-agent.service` (Linux)

**Usage:** `devboy secrets agent install [OPTIONS]`

###### **Options:**

* `--binary <BINARY>` — Override the path to the `devboy-secrets-agent` binary. By default the same lookup as `secrets agent start` is used (env override → sibling-of-current_exe → `PATH`)
* `--socket <SOCKET>` — Override the daemon's socket path (`DEVBOY_AGENT_SOCKET`)
* `--vault <VAULT>` — Override the daemon's vault path (`DEVBOY_VAULT_PATH`)
* `--no-load` — Skip the platform service-manager activation step (just write the unit file). Useful for previewing what would land on disk; the unit is loaded next time `launchctl/systemctl` scans its directory anyway

  Default value: `false`



## `devboy secrets agent uninstall`

Stop the user service (if loaded) and remove the unit file written by `install`. Idempotent — running it twice is fine

**Usage:** `devboy secrets agent uninstall [OPTIONS]`

###### **Options:**

* `--no-unload` — Skip the platform service-manager teardown step (just remove the unit file). The next reboot will pick up the removal anyway

  Default value: `false`



## `devboy secrets ui`

Open the native UI (TUI in a terminal, GUI in a window). Backend autodetected from `$DISPLAY` / `$WAYLAND_DISPLAY` on Linux and the OS on macOS / Windows; override with `--tui` or `--gui`. See ADR-023 §3.4

**Usage:** `devboy secrets ui [OPTIONS]`

###### **Options:**

* `--tui` — Force the terminal renderer (ratatui)
* `--gui` — Force the windowed renderer (egui). Opens a native window via eframe; runs until the user closes it
* `--provision <PATH>` — Open the provision dialog focused on the given path. The window still opens with the full inventory in the background, but the dialog overlay is armed at startup — useful when the AI agent (or a script) wants to put the user one click away from filling a known-missing secret. Path must be valid ADR-020



## `devboy secrets rotate`

Rotate a secret: open the provider URL in the browser, destructive-confirm, read the new value, format-validate, and record `last_rotated_at`. See ADR-023 §3.4

**Usage:** `devboy secrets rotate [OPTIONS] <PATH>`

###### **Arguments:**

* `<PATH>` — ADR-020 path of the secret to rotate (e.g. `team/jira/api-key`)

###### **Options:**

* `--no-browser` — Skip the OS-browser hand-off. Useful in CI / scripts that rotate values fetched out-of-band
* `--yes` — Skip the destructive-confirm prompt. Required when stdin isn't a TTY (the prompt would have nothing to read)
* `--from-stdin` — Read the new value from stdin (one line, no echo) instead of the interactive prompt. Useful for `vault read` / `op read` shell pipelines and for tests
* `--index <INDEX>` — Override the path the global index is loaded from / saved to. Defaults to the platform's config dir



## `devboy secrets catalog`

Manage the token catalog (provider procedure files the `secrets ui` form binds to). See ADR-023 §3.4

**Usage:** `devboy secrets catalog <COMMAND>`

###### **Subcommands:**

* `list` — List every loaded provider catalog with its source (bundled / user / project) and variant count. Useful to debug which override is winning when a team has its own project-scope file shadowing the bundled default
* `status` — Inspect every catalog at every active source — bundled, user, project, AND URL — with origin, variant count, and (for URL sources) cache state. Replaces the older `list` command for the URL-loaded catalog flow (P23)
* `add-url` — Subscribe to a remote catalog by URL. Fetches once through every P23 defence layer (HTTPS-only, SSRF guard, size cap, content-type, schema version), prints the body SHA256 + variant summary, asks for trust confirmation (or accepts a `--pin` for unattended use), then appends a `[[source]]` entry to `~/.devboy/secrets/catalog/sources.toml`
* `refresh` — Re-fetch URL catalogs from `sources.toml`. Without `--force` the loader honours each source's `refresh_seconds` TTL — sources within their window are reported as "fresh" and not re-fetched. With `--force` the cache for matching sources is dropped before the fetch so every source goes back to the network. Optional positional `<filter>` matches as a case-insensitive substring against the source URL
* `forget` — Drop URL entries from `known_hashes.toml` so the next fetch re-establishes TOFU. Positional `<filter>` is a case-insensitive URL substring; without it, every recorded entry is dropped (with confirmation unless `--yes` is set). Use this after a deliberate upstream rotation that you want devboy to re-trust
* `pin` — Promote a TOFU entry to a hard SHA pin in `sources.toml`. Positional `<filter>` is a case- insensitive URL substring matching the source to pin. With explicit `<sha>` argument, that exact value is written; without it, the current `known_hashes.toml` entry is read and copied. Future fetches from this source refuse any mismatch
* `validate` — Validate a single catalog JSON file. Loads the file, runs schema deserialisation (`deny_unknown_fields` is strict), then per-variant checks that the regex compiles and that every URL parses. Exit non-zero on any failure



## `devboy secrets catalog list`

List every loaded provider catalog with its source (bundled / user / project) and variant count. Useful to debug which override is winning when a team has its own project-scope file shadowing the bundled default

**Usage:** `devboy secrets catalog list`



## `devboy secrets catalog status`

Inspect every catalog at every active source — bundled, user, project, AND URL — with origin, variant count, and (for URL sources) cache state. Replaces the older `list` command for the URL-loaded catalog flow (P23)

**Usage:** `devboy secrets catalog status [OPTIONS]`

###### **Options:**

* `--json` — Print as machine-readable JSON instead of a human table



## `devboy secrets catalog add-url`

Subscribe to a remote catalog by URL. Fetches once through every P23 defence layer (HTTPS-only, SSRF guard, size cap, content-type, schema version), prints the body SHA256 + variant summary, asks for trust confirmation (or accepts a `--pin` for unattended use), then appends a `[[source]]` entry to `~/.devboy/secrets/catalog/sources.toml`

**Usage:** `devboy secrets catalog add-url [OPTIONS] <URL>`

###### **Arguments:**

* `<URL>` — HTTPS URL of the JSON catalog (e.g. a GitHub raw link). `http://` is rejected outright by the fetcher's first defence layer

###### **Options:**

* `--pin <HEX>` — Pin the body to this SHA256 (lower-case hex, no `sha256:` prefix). Future fetches refuse any mismatch. When omitted, the loader falls back to TOFU and records the body's SHA in `known_hashes.toml` on first fetch
* `--refresh-seconds <REFRESH_SECONDS>` — How long the cached body stays fresh before the loader re-fetches. Defaults to 24 hours

  Default value: `86400`
* `--enable` — Also flip `enable_url_catalogs = true` in the same `sources.toml`. Without this flag the entry is added but the master kill-switch remains off — the URL is not loaded until the user explicitly enables it
* `--yes` — Skip the interactive trust-confirm prompt. Implied when `--pin` is set (the pin already locks the body). Required for non-tty / CI invocations



## `devboy secrets catalog refresh`

Re-fetch URL catalogs from `sources.toml`. Without `--force` the loader honours each source's `refresh_seconds` TTL — sources within their window are reported as "fresh" and not re-fetched. With `--force` the cache for matching sources is dropped before the fetch so every source goes back to the network. Optional positional `<filter>` matches as a case-insensitive substring against the source URL

**Usage:** `devboy secrets catalog refresh [OPTIONS] [FILTER]`

###### **Arguments:**

* `<FILTER>` — Optional case-insensitive substring; only sources whose URL matches are re-fetched. Without this argument every URL source is processed

###### **Options:**

* `--force` — Bypass each source's `refresh_seconds` TTL and force a re-fetch over the network. Cache for matching sources is removed before the fetch so the loader cannot serve a stale body



## `devboy secrets catalog forget`

Drop URL entries from `known_hashes.toml` so the next fetch re-establishes TOFU. Positional `<filter>` is a case-insensitive URL substring; without it, every recorded entry is dropped (with confirmation unless `--yes` is set). Use this after a deliberate upstream rotation that you want devboy to re-trust

**Usage:** `devboy secrets catalog forget [OPTIONS] [FILTER]`

###### **Arguments:**

* `<FILTER>` — Optional case-insensitive substring against the URL. Without this argument, every recorded TOFU entry is dropped (subject to `--yes`)

###### **Options:**

* `--yes` — Skip the interactive confirmation prompt. Required when no filter is given (bulk-clearing all TOFU entries is destructive enough to warrant explicit opt-in)



## `devboy secrets catalog pin`

Promote a TOFU entry to a hard SHA pin in `sources.toml`. Positional `<filter>` is a case- insensitive URL substring matching the source to pin. With explicit `<sha>` argument, that exact value is written; without it, the current `known_hashes.toml` entry is read and copied. Future fetches from this source refuse any mismatch

**Usage:** `devboy secrets catalog pin <FILTER> [SHA]`

###### **Arguments:**

* `<FILTER>` — Case-insensitive URL substring identifying the source to pin. Must match exactly one source; ambiguity is an error
* `<SHA>` — Explicit lower-case-hex SHA256 to write to `sources.toml`. When omitted, the current TOFU entry for the matched source is read from `known_hashes.toml` and copied



## `devboy secrets catalog validate`

Validate a single catalog JSON file. Loads the file, runs schema deserialisation (`deny_unknown_fields` is strict), then per-variant checks that the regex compiles and that every URL parses. Exit non-zero on any failure

**Usage:** `devboy secrets catalog validate <PATH>`

###### **Arguments:**

* `<PATH>` — Path to the JSON catalog file. Use `-` to read from stdin



## `devboy secrets setup`

Run the setup-secrets wizard against the current directory. Default mode is `--scan-only` — read-only preview of what the wizard would propose. Pass `--write-manifest` to commit the proposals to `<repo>/.devboy/secrets.toml`. See ADR-023 §3.8 and `crates/devboy-skills/skills/00-self-bootstrap/setup-secrets/`

**Usage:** `devboy secrets setup [OPTIONS]`

###### **Options:**

* `--root <ROOT>` — Project root to scan. Defaults to the current directory
* `--scan-only` — Print the scan + propose preview without touching disk. This is the default mode — included as an explicit flag for self-documenting scripts
* `--write-manifest` — Commit the proposed paths to `<root>/.devboy/secrets.toml`. Refuses to overwrite an existing manifest unless `--force` is passed too — drift in the manifest is the user's own authoritative copy and the wizard treats it as opaque
* `--force` — Allow `--write-manifest` to overwrite an existing `<root>/.devboy/secrets.toml`. No-op without `--write-manifest`
* `--resume` — Resume the wizard from the recorded state file (`~/.devboy/secrets/setup-state.toml`). Skips phases already marked `done` / `skipped`. Implies a full wizard run, not just the scan preview
* `--json` — Emit JSON-lines events to stdout instead of human prose. One event per line with shape `{"phase":"scan","status":"completed","message":"…"}` — designed for the AI agent driving the skill. The `message` key is optional: only `PhaseProgress`, `PhaseCompleted`, `PhaseSkipped`, and `PhaseFailed` carry a body; `PhaseStarted` and the terminal `wizard-completed` event omit it



## `devboy secrets kdbx`

Work with KDBX 4 (KeePass) files as a SecretSource. The passphrase is prompted from stdin with no echo; the decrypted body lives only inside this process and is dropped on exit. See ADR-021 §8 + `crates/plugins/secrets/kdbx/`

**Usage:** `devboy secrets kdbx <COMMAND>`

###### **Subcommands:**

* `peek` — Open a `.kdbx` file with a prompted passphrase and print the per-entry inventory (path + Title + UserName + URL + whether a Password is set). Values are NEVER printed — this is a read-only sanity check that the file opens and our path normalisation produces sensible references
* `describe-metadata` — Read-only metadata projection for ONE entry by UUID. Prints title / username / url / notes / tags / expires_at / attachment names / custom-string names. Password and every Protected custom string are deliberately excluded from the output — same agent-blindness boundary as `edit-metadata` (K14)
* `edit-metadata` — Edit non-value metadata on ONE entry by UUID. Allows updating title / username / url / notes / tags / expiry timestamp; the value-bearing Password and any Protected custom string are unreachable from this surface. Writes through `derive_working_copy_path` so the user's original `.kdbx` is never overwritten — the working copy path is printed at the end so callers can sync back on their own schedule



## `devboy secrets kdbx peek`

Open a `.kdbx` file with a prompted passphrase and print the per-entry inventory (path + Title + UserName + URL + whether a Password is set). Values are NEVER printed — this is a read-only sanity check that the file opens and our path normalisation produces sensible references

**Usage:** `devboy secrets kdbx peek [OPTIONS] --file <FILE>`

###### **Options:**

* `--file <FILE>` — Absolute path to the `.kdbx` file. Required — there is no default discovery for KDBX files (the user opts in per-invocation)
* `--keyfile <KEYFILE>` — Optional path to a keyfile companion (KeePass two-factor unlock). Omit for passphrase-only databases
* `--json` — Print as JSON (one entry per object) instead of the default human table. Useful for scripted verification



## `devboy secrets kdbx describe-metadata`

Read-only metadata projection for ONE entry by UUID. Prints title / username / url / notes / tags / expires_at / attachment names / custom-string names. Password and every Protected custom string are deliberately excluded from the output — same agent-blindness boundary as `edit-metadata` (K14)

**Usage:** `devboy secrets kdbx describe-metadata [OPTIONS] --file <FILE> --uuid <UUID>`

###### **Options:**

* `--file <FILE>` — Absolute path to the `.kdbx` file
* `--keyfile <KEYFILE>` — Optional keyfile companion (KeePass two-factor unlock)
* `--uuid <UUID>` — UUID of the entry to project. Hyphenated hex (`12345678-90ab-cdef-1234-567890abcdef`). See `kdbx peek --json` for a complete UUID listing
* `--json` — Print as JSON instead of the default human key/value table. JSON output is the contract for scripted / MCP-wrapper consumers



## `devboy secrets kdbx edit-metadata`

Edit non-value metadata on ONE entry by UUID. Allows updating title / username / url / notes / tags / expiry timestamp; the value-bearing Password and any Protected custom string are unreachable from this surface. Writes through `derive_working_copy_path` so the user's original `.kdbx` is never overwritten — the working copy path is printed at the end so callers can sync back on their own schedule

**Usage:** `devboy secrets kdbx edit-metadata [OPTIONS] --file <FILE> --uuid <UUID>`

###### **Options:**

* `--file <FILE>` — Absolute path to the `.kdbx` file. The edit goes to the derived working copy, not this path — see the printed `working_copy` line on success
* `--keyfile <KEYFILE>` — Optional keyfile companion (KeePass two-factor unlock)
* `--uuid <UUID>` — UUID of the entry to edit. Hyphenated hex
* `--title <TITLE>` — New Title. Empty string clears
* `--username <USERNAME>` — New UserName. Empty string clears
* `--url <URL>` — New URL. Empty string clears
* `--notes <NOTES>` — New Notes (multiline allowed via shell escapes / `--notes "$(cat notes.md)"`). Empty string clears
* `--tag <TAGS>` — Replace the tag list with these values. Pass `--tag` once per tag; omit the flag entirely to leave existing tags alone; pass `--clear-tags` to drop all tags
* `--clear-tags` — Wipe all tags on the entry. Mutually exclusive with `--tag`; if both appear, `--clear-tags` wins
* `--expires-at <ISO8601>` — New expiry timestamp (RFC 3339, e.g. `2027-01-15T00:00:00Z`). Pass `--no-expiry` to clear an existing expiry. Without either, the field is left alone
* `--no-expiry` — Clear any existing expiry timestamp. Mutually exclusive with `--expires-at`; if both appear, `--no-expiry` wins
* `--json` — Print as JSON instead of the default human summary



## `devboy hooks`

Manage git hooks installed by devboy (e.g. the secret-alias pre-commit lint, ADR-020 §5)

**Usage:** `devboy hooks <COMMAND>`

###### **Subcommands:**

* `install` — Install git hooks. Currently only the secret-alias-lint pre-commit hook is supported; future hooks land as additional flags on the same subcommand
* `check` — Run a hook check directly. Used by the installed hooks but also as a standalone way to lint the staged diff before committing



## `devboy hooks install`

Install git hooks. Currently only the secret-alias-lint pre-commit hook is supported; future hooks land as additional flags on the same subcommand

**Usage:** `devboy hooks install [OPTIONS]`

###### **Options:**

* `--secret-alias-lint` — Install the secret-alias pre-commit lint. Currently the only thing `install` knows about; the flag is required so future hooks can be added without changing the verb
* `-f`, `--force` — Replace an existing `pre-commit` hook. Without this the install refuses when the hook file already exists

  Default value: `false`



## `devboy hooks check`

Run a hook check directly. Used by the installed hooks but also as a standalone way to lint the staged diff before committing

**Usage:** `devboy hooks check <COMMAND>`

###### **Subcommands:**

* `secret-alias` — Scan the staged git diff for `@secret:<path>` aliases in files not known to be alias-aware. Exits non-zero on hits



## `devboy hooks check secret-alias`

Scan the staged git diff for `@secret:<path>` aliases in files not known to be alias-aware. Exits non-zero on hits

**Usage:** `devboy hooks check secret-alias [OPTIONS]`

###### **Options:**

* `--repo <REPO>` — Override the working directory the check runs in. Mostly useful for tests; defaults to the current process CWD



## `devboy trace`

Write to a skill's self-feedback session trace (ADR-015)

**Usage:** `devboy trace <COMMAND>`

###### **Subcommands:**

* `begin` — Start a new session trace. Prints a single JSON line with `session_id`, `session_dir`, `trace_path` — skills capture that and pass the values to subsequent `event` / `end` invocations
* `event` — Append one event to an existing session
* `end` — Finalise a session — writes the closing event and updates `meta.json` with the outcome + aggregated counts



## `devboy trace begin`

Start a new session trace. Prints a single JSON line with `session_id`, `session_dir`, `trace_path` — skills capture that and pass the values to subsequent `event` / `end` invocations

**Usage:** `devboy trace begin [OPTIONS] --skill <SKILL>`

###### **Options:**

* `--skill <SKILL>` — Skill name. Shown as the directory under the date, also recorded in every event
* `--global` — Write under `~/.devboy/sessions/` instead of the repo-local `<repo>/.devboy/sessions/`
* `--dir <DIR>` — Write under an explicit directory (mostly for testing)



## `devboy trace event`

Append one event to an existing session

**Usage:** `devboy trace event [OPTIONS] --session-dir <SESSION_DIR> --session-id <SESSION_ID> --skill <SKILL> --phase <PHASE>`

###### **Options:**

* `--session-dir <SESSION_DIR>` — Session directory printed by `trace begin`
* `--session-id <SESSION_ID>` — Session id printed by `trace begin`
* `--skill <SKILL>` — Skill name
* `--phase <PHASE>` — Event phase. Supported values: `start`, `decision`, `tool_call`, `tool_result`, `verify`, `artifact`, `note`, `end`
* `--payload <PAYLOAD>` — JSON payload. Defaults to `{}` if omitted

  Default value: `{}`



## `devboy trace end`

Finalise a session — writes the closing event and updates `meta.json` with the outcome + aggregated counts

**Usage:** `devboy trace end [OPTIONS] --session-dir <SESSION_DIR> --session-id <SESSION_ID> --skill <SKILL> --outcome <OUTCOME>`

###### **Options:**

* `--session-dir <SESSION_DIR>` — Session directory printed by `trace begin`
* `--session-id <SESSION_ID>` — Session id printed by `trace begin`
* `--skill <SKILL>` — Skill name
* `--outcome <OUTCOME>` — Session outcome: `success`, `failure`, `aborted`
* `--summary <SUMMARY>` — Human-readable summary

  Default value: ``



## `devboy doctor`

Run diagnostic checks for the local DevBoy setup

**Usage:** `devboy doctor [OPTIONS]`

###### **Options:**

* `--format <FORMAT>` — Output machine-readable JSON

  Possible values: `console`, `json`

* `--list-checks` — List available check IDs and exit
* `--checks <CHECKS>` — Run only the specified check IDs (comma-delimited or repeated)
* `--secrets` — Shorthand for `--checks context-secrets` — focuses doctor on the secret-framework checks (manifest gating, missing values, format validation, source health). See ADR-023 §3.7



## `devboy upgrade`

Upgrade devboy to the latest version

**Usage:** `devboy upgrade [OPTIONS]`

###### **Options:**

* `--check` — Only check for updates, don't install



## `devboy benchmark`

Benchmark format pipeline on real open-source project data (JSON vs TOON)

**Usage:** `devboy benchmark [OPTIONS]`

###### **Options:**

* `-o`, `--owner <OWNER>` — GitHub owner (e.g., "kubernetes")

  Default value: `facebook`
* `-r`, `--repo <REPO>` — GitHub repo (e.g., "kubernetes")

  Default value: `react`
* `-b`, `--budget <BUDGET>` — Token budget (default: 8000)

  Default value: `8000`
* `-n`, `--limit <LIMIT>` — Maximum issues to fetch (default: 30)

  Default value: `30`
* `--token <TOKEN>` — GitHub token (optional, for higher rate limits). Set GITHUB_TOKEN env var



## `devboy format-pipeline`

Format JSON from stdin through the TOON pipeline (pipe mode)

Usage: cat issues.json | devboy format-pipeline

**Usage:** `devboy format-pipeline [OPTIONS]`

###### **Options:**

* `-t`, `--data-type <TYPE>` — Data type: issues, merge_requests, diffs, comments, discussions (auto-detected if omitted)
* `-b`, `--budget <BUDGET>` — Token budget (default: 8000, minimum: 1)

  Default value: `8000`
* `-s`, `--strategy <STRATEGY>` — Trimming strategy

  Possible values: `element_count`, `cascading`, `size_proportional`, `thread_level`, `head_tail`, `default`

* `-l`, `--level <LEVEL>` — Trim level

  Default value: `full`

  Possible values: `full`, `standard`, `minimal`

* `-f`, `--format <FORMAT>` — Output format (JSON mode still applies budget trimming)

  Default value: `toon`

  Possible values: `toon`, `json`

* `--stats` — Print token savings stats to stderr



<hr/>

<small><i>
    This document was generated automatically by
    <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>
