# 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 name for the configuration * `--proxy ` — Add MCP proxy server URL * `--proxy-only` — Only configure proxy, skip git remote auto-detection * `--proxy-name ` — Proxy server name (default: "proxy") * `--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 ` — Keychain key for proxy token (e.g., "proxy.token") * `--proxy-token ` — Proxy token value (will be stored in keychain automatically) * `--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 (fetched on startup, TOML response merged with local config) * `--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 ` ###### **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 ` ###### **Arguments:** * `` — Config key (e.g., github.owner, gitlab.url) * `` — 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 ` ###### **Arguments:** * `` — Secret key (e.g., github.token, gitlab.token) * `` — Secret value (will be stored securely) ## `devboy config get` Get a configuration value **Usage:** `devboy config get ` ###### **Arguments:** * `` — 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 ` ###### **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 ` ###### **Arguments:** * `` ## `devboy issues` Get information about issues **Usage:** `devboy issues [OPTIONS]` ###### **Options:** * `-s`, `--state ` — Filter by state Default value: `open` Possible values: `open`, `closed`, `all` * `-l`, `--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 ` — Filter by state Default value: `open` Possible values: `open`, `merged`, `closed`, `all` * `-l`, `--limit ` — Maximum number of MRs to display Default value: `20` ## `devboy test` Test provider connection **Usage:** `devboy test ` ###### **Arguments:** * `` — Provider to test (github, gitlab, clickup, jira, slack) ## `devboy proxy` Interact with upstream MCP proxy servers **Usage:** `devboy proxy ` ###### **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 ` ###### **Arguments:** * `` — Proxy server name ###### **Options:** * `--url ` — Proxy server URL * `--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 ` — Keychain key for proxy token (e.g., "proxy.token") * `--token ` — Token value (will be stored in keychain automatically) * `--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 ` ###### **Arguments:** * `` — 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 [ARGS]` ###### **Arguments:** * `` — Tool name (e.g., devboy-cloud__get_issues) * `` — 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 ...` ###### **Arguments:** * `` — Tool names to disable ## `devboy tools enable` Enable specific built-in tools (remove from disabled list) **Usage:** `devboy tools enable ...` ###### **Arguments:** * `` — 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 [ARGS]` ###### **Arguments:** * `` — Tool name (e.g., get_issues, list_contexts) * `` — JSON arguments (optional) Default value: `{}` ## `devboy tools docs` Generate auto-built reference docs for built-in tools **Usage:** `devboy tools docs [OPTIONS]` ###### **Options:** * `--format ` — Output format Default value: `markdown` Possible values: `markdown`, `json` * `--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 ` ###### **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 ` — 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 ` — 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 ` ###### **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 ` — 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 ` ###### **Arguments:** * `` — Skill name ## `devboy skills install` Install one or more skills to the resolved target(s) **Usage:** `devboy skills install [OPTIONS] [NAMES]...` ###### **Arguments:** * `` — Skill names. Ignored when `--all` or `--category` is used ###### **Options:** * `--all` — Install every skill the embedded source knows about * `--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 ` — 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:** * `` — 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 ` — 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] ...` ###### **Arguments:** * `` — Skill names to remove ###### **Options:** * `--global` — Counterpart to `--agent` (see `install`) * `--local` — Counterpart to `--agent` (see `install`) * `--agent ` — 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 ` ###### **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 ` — 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 ` — Override the auto-detected primary agent (e.g. `--agent claude`) * `--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 ` ###### **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 `/.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] ` ###### **Arguments:** * `` — 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:** * `` — 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 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 ` — 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 ` 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 ` ###### **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 ` — Override the vault file the daemon will operate on. Defaults to `/devboy-tools/secrets/vault.dvb` * `--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 ` — 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 ` — Override the daemon's socket path (`DEVBOY_AGENT_SOCKET`) * `--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 ` — 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] ` ###### **Arguments:** * `` — 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 ` — 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 ` ###### **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 `` 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 `` 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 `` is a case- insensitive URL substring matching the source to pin. With explicit `` 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] ` ###### **Arguments:** * `` — 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 ` — 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 ` — 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 `` matches as a case-insensitive substring against the source URL **Usage:** `devboy secrets catalog refresh [OPTIONS] [FILTER]` ###### **Arguments:** * `` — 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 `` 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:** * `` — 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 `` is a case- insensitive URL substring matching the source to pin. With explicit `` 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 [SHA]` ###### **Arguments:** * `` — Case-insensitive URL substring identifying the source to pin. Must match exactly one source; ambiguity is an error * `` — 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 ` ###### **Arguments:** * `` — 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 `/.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 ` — 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 `/.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 `/.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 ` ###### **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 ` ###### **Options:** * `--file ` — Absolute path to the `.kdbx` file. Required — there is no default discovery for KDBX files (the user opts in per-invocation) * `--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 --uuid ` ###### **Options:** * `--file ` — Absolute path to the `.kdbx` file * `--keyfile ` — Optional keyfile companion (KeePass two-factor unlock) * `--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 --uuid ` ###### **Options:** * `--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 ` — Optional keyfile companion (KeePass two-factor unlock) * `--uuid ` — UUID of the entry to edit. Hyphenated hex * `--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>