DevBoy tools

    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 - 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

    This document was generated automatically by clap-markdown.