contrib: Add bash completion for new bitcoin command #33385

caesrcd commented at 3:34 PM on September 13, 2025: contributor

Adds a bash completion script for the new bitcoin command-line tool (introduced in #31375), which unifies the main Bitcoin Core executables under a single interface. This feature improves usability, reduces errors, and makes the command-line tools more easily discoverable for users working in a Linux bash environment.

The completion script dynamically lists available commands and options by parsing bitcoin --help and bitcoin help. It also incorporates the existing bash completions for bitcoind, bitcoin-cli, and bitcoin-tx, depending on the argument provided (node, gui, rpc, or tx). This ensures that all relevant completions are available seamlessly through a single interface without modifying core functionality.

Key points:

Improves developer and user experience on the command line.
Does not modify or replace existing functionality.
Placed under contrib/ for easy installation by users and distributions.

DrahtBot added the label Scripts and tools on Sep 13, 2025

DrahtBot closed this on Sep 13, 2025

DrahtBot commented at 3:34 PM on September 13, 2025: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33385.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	willcl-ark, BrandonOdiwuor
Stale ACK	epcgrs

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

Conflicts

No conflicts as of last run.

fanquake reopened this on Sep 13, 2025

caesrcd force-pushed on Sep 14, 2025

bitcoin deleted a comment on Sep 15, 2025

caesrcd renamed this:
~~contrib: add bash completion for new bitcoin command~~
contrib: Add bash completion for new bitcoin command
on Sep 16, 2025

epcgrs commented at 2:43 AM on September 19, 2025: none

utACK b5d45f0

Well structured;
Good practices with bash scripting;
Dynamic search using help;

LGTM

epcgrs commented at 8:10 PM on October 11, 2025: none

ACK b5d45f0

prusnak commented at 6:51 AM on October 13, 2025: contributor

ISTM "bitcoin test" is not covered

caesrcd commented at 11:56 AM on October 13, 2025: contributor

@prusnak It will complete the arguments of bitcoin itself and the subarguments of commands that already have their own completion.

To cover bitcoin test, a completion script for the test_bitcoin command would need to be created.

in contrib/completions/bash/bitcoin.bash:2 in b5d45f0601

   0 | @@ -0,0 +1,95 @@
   1 | +# bash programmable completion for bitcoin(1) wrapper
   2 | +# Copyright (c) 2025 CaesarCoder <caesrcd@tutamail.com>

willcl-ark commented at 11:36 AM on March 4, 2026:

Please use

Copyright (c) 2026-present The Bitcoin Core developers

caesrcd commented at 12:47 PM on March 4, 2026:

Done

in contrib/completions/bash/bitcoin.bash:57 in b5d45f0601

  52 | +            ;;
  53 | +        -m|-M)
  54 | +            if [[ "${words[2]}" == "node" ]]; then
  55 | +                _bitcoin_wrap bitcoind 3
  56 | +                return 0
  57 | +            fi

willcl-ark commented at 11:38 AM on March 4, 2026:

This drops rpc and tx delegations.

When the user types bitcoin -m rpc <TAB>, words[1] is -m so the node/rpc/tx case (L43) doesn't match. It falls through to the -m|-M case (L53) which only checks for node at words[2]. So bitcoin -m rpc <TAB> would show top-level bitcoin help instead of RPC methods.

The same applies to bitcoin -m tx <TAB>.

willcl-ark commented at 11:38 AM on March 4, 2026:

bitcoin --multiprocess node <TAB> (longform) also falls through to the generic handler.

caesrcd commented at 1:06 PM on March 4, 2026:

This drops rpc and tx delegations.

According to the bitcoin help output, the -m|-M flags are explicitly defined as execution mode selectors for the node and gui commands only. They control whether the multiprocess binaries (bitcoin-node, bitcoin-gui) or the monolithic binaries (bitcoind, bitcoin-qt) are executed.

They are not specified as applicable to the rpc or tx commands.

For reference:

bitcoin help
Usage: bitcoin [OPTIONS] COMMAND...

Options:
  -m, --multiprocess     Run multiprocess binaries bitcoin-node, bitcoin-gui.
  -M, --monolithic       Run monolithic binaries bitcoind, bitcoin-qt. (Default behavior)
  -v, --version          Show version information
  -h, --help             Show full help message

Commands:
  gui [ARGS]     Start GUI, equivalent to running 'bitcoin-qt [ARGS]' or 'bitcoin-gui [ARGS]'.
  node [ARGS]    Start node, equivalent to running 'bitcoind [ARGS]' or 'bitcoin-node [ARGS]'.
  rpc [ARGS]     Call RPC method, equivalent to running 'bitcoin-cli -named [ARGS]'.
  wallet [ARGS]  Call wallet command, equivalent to running 'bitcoin-wallet [ARGS]'.
  tx [ARGS]      Manipulate hex-encoded transactions, equivalent to running 'bitcoin-tx [ARGS]'.
  help           Show full help message.

Since -m|-M only affect node and gui, and there is currently no autocomplete implementation for gui, autocomplete support was added only for node.

Therefore, bitcoin -m rpc and bitcoin -m tx are not considered valid command combinations according to the documented CLI, and the current autocomplete behavior reflects that design.

willcl-ark commented at 1:08 PM on March 4, 2026:

I think that's just to avoid listing all binaries. For example, this works:

src/core/bitcoin on  pr-33385 [$?] via △ v4.1.2 via 🐍 v3.13.11 via ❄️  impure (nix-shell-env)
❯ ./build/bin/bitcoin -m tx
Bitcoin Core bitcoin-tx utility version v30.99.0-b5d45f060161

The bitcoin-tx tool is used for creating and modifying bitcoin transactions.

caesrcd commented at 1:56 PM on March 4, 2026:

Done. Autocompletion for the node/rpc/tx commands now works regardless of whether -m|-M|--multiprocess|--monolithic are provided.

in contrib/completions/bash/bitcoin.bash:40 in b5d45f0601 outdated

  35 | +    bitcoin="$1"
  36 | +
  37 | +    COMPREPLY=()
  38 | +    _get_comp_words_by_ref -n = cur prev words cword
  39 | +
  40 | +    case "${words[1]}" in

willcl-ark commented at 11:39 AM on March 4, 2026:

This is not handling gui. I think this is probably OK and could be done in a followup though.

in contrib/completions/bash/bitcoin.bash:68 in b5d45f0601

  63 | +            return 0
  64 | +            ;;
  65 | +        *)
  66 | +            local options commands
  67 | +
  68 | +            # only parse help if senseful

willcl-ark commented at 11:40 AM on March 4, 2026:

            # only parse help if sensible

caesrcd commented at 1:47 PM on March 4, 2026:

Done

in contrib/completions/bash/bitcoin.bash:70 in b5d45f0601 outdated

  65 | +        *)
  66 | +            local options commands
  67 | +
  68 | +            # only parse help if senseful
  69 | +            if [[ -z "$cur" || "$cur" =~ ^- ]]; then
  70 | +                options=$($bitcoin help 2>&1 | awk '{ for(i=1;i<=NF;i++) if ($i~/^--/) { sub(/=.*/, "=",$i); print $i } }' )

willcl-ark commented at 11:40 AM on March 4, 2026:

IIUC this disallows non-double-dash options, e.g. -m, -M, -v, -h

caesrcd commented at 1:23 PM on March 4, 2026:

I intentionally chose to expose only the long-form options (--multiprocess, --monolithic, --version, --help) instead of the short aliases (-m, -M, -v, -h).

The rationale is that the long options are self-descriptive and improve clarity in the autocomplete output, whereas the short flags provide less contextual information and can reduce readability. Since both forms are functionally equivalent at the CLI level, prioritizing the explicit variants helps make the suggestions more intuitive without removing any actual functionality.

willcl-ark commented at 1:32 PM on March 4, 2026:

OK, that seems fair enough to me. Thanks for exaplaining.

willcl-ark changes_requested

willcl-ark commented at 11:42 AM on March 4, 2026: member

Concept ACK.

I think these needs a few changes still, but is a good start in the right direction.

Manual testing looks OK, less the nits in my comments:

[nix-shell:~/src/core/bitcoin]$ source contrib/completions/bash/bitcoin.bash

[nix-shell:~/src/core/bitcoin]$ bitcoin
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

[nix-shell:~/src/core/bitcoin]$ bitcoin --
--help          --monolithic    --multiprocess  --version

[nix-shell:~/src/core/bitcoin]$ bitcoin node -
Display all 136 possibilities? (y or n)

[nix-shell:~/src/core/bitcoin]$ bitcoin node -data
-datacarrier      -datacarriersize  -datadir=

[nix-shell:~/src/core/bitcoin]$ bitcoin node -datadir=
build/       ci/          cmake/       depends/     .git/        .ruff_cache/ src/         .tx/
.cache/      .claude/     contrib/     doc/         .github/     share/       test/

[nix-shell:~/src/core/bitcoin]$ bitcoin rpc
Display all 181 possibilities? (y or n)

[nix-shell:~/src/core/bitcoin]$ bitcoin rpc getblock
getblock           getblockcount      getblockfrompeer   getblockheader     getblocktemplate
getblockchaininfo  getblockfilter     getblockhash       getblockstats

[nix-shell:~/src/core/bitcoin]$ bitcoin tx -
-chain=<chain>    -help             -signet           -signetseednode   -testnet4         -version
-create           -json             -signetchallenge  -testnet          -txid

[nix-shell:~/src/core/bitcoin]$ bitcoin tx -create
delin=         in=            locktime=      outaddr=       outmultisig=   outscript=     set=
delout=        load=          nversion=      outdata=       outpubkey=     replaceable(=  sign=

[nix-shell:~/src/core/bitcoin]$ bitcoin -m rpc
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

[nix-shell:~/src/core/bitcoin]$ bitcoin -m tx
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

[nix-shell:~/src/core/bitcoin]$ bitcoin --multiprocess node
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

[nix-shell:~/src/core/bitcoin]$ bitcoin guix
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

[nix-shell:~/src/core/bitcoin]$ bitcoin gui
bench           gui             help            --multiprocess  rpc             test-gui        --version
chainstate      --help          --monolithic    node            test            tx              wallet

caesrcd force-pushed on Mar 4, 2026

caesrcd commented at 1:46 PM on March 4, 2026: contributor

Rebased

caesrcd requested review from willcl-ark on Mar 4, 2026

in contrib/completions/bash/bitcoin.bash:31 in d5c58446be

  26 | +    $func "$delegate"
  27 | +}
  28 | +
  29 | +_bitcoin() {
  30 | +    local cur prev words cword
  31 | +    local bitcoin, subcmd, offset

willcl-ark commented at 9:56 AM on March 5, 2026:

local delineates using spaces, not commas. In fact these cause errors on completion:

[nix-shell:~/src/core/worktrees/pr-33385]$ ./build/bin/bitcoin -bash: local: `bitcoin,': not a valid identifier
bash: local: `subcmd,': not a valid identifier
-bash: local: `bitcoin,': not a valid identifier
bash: local: `subcmd,': not a valid identifier

    local bitcoin subcmd offset

caesrcd commented at 12:59 PM on March 5, 2026:

Thank you for pointing that out. Since it did not reproduce on my side, it unfortunately went unnoticed during my testing.

in contrib/completions/bash/bitcoin.bash:52 in d5c58446be

  47 | +            offset=2
  48 | +            ;;
  49 | +    esac
  50 | +
  51 | +    case "$subcmd" in
  52 | +        node)

willcl-ark commented at 9:58 AM on March 5, 2026:

I wonder if here we should have:

        gui | node)

To delegate gui to bitcoind options?

caesrcd commented at 1:11 PM on March 5, 2026:

Good catch. Since bitcoin-gui is not built by default, I hadn’t tested that command specifically, as I assumed it behaved differently from bitcoind or bitcoin-node.

in contrib/completions/bash/bitcoin.bash:24 in d5c58446be

  19 | +
  20 | +    _get_comp_words_by_ref -n = words cword
  21 | +
  22 | +    COMP_WORDS=( "$delegate" "${words[@]:$shift_count}" )
  23 | +    COMP_CWORD=$(( cword - (shift_count - 1) ))
  24 | +    COMP_LINE="${COMP_WORDS[@]}"

willcl-ark commented at 10:01 AM on March 5, 2026:

I did wonder about using this:

    COMP_LINE="${COMP_WORDS[*]}"

But I think both are functionally identical here. * gets seperate strings vs @ seperate words. I think both are OK though.

caesrcd commented at 1:21 PM on March 5, 2026:

I tested both and did not observe any differences. I decided to keep the current behavior as-is based on recommendations discussed in various forums.

willcl-ark changes_requested

willcl-ark commented at 10:01 AM on March 5, 2026: member

thanks for your quick update.

just left a few more comments, looks pretty good to me now though :)

contrib: Add bash completion for new bitcoin command

Adds a bash completion script for the new bitcoin command-line
tool, which unifies the main Bitcoin Core executables under a
single interface. This feature improves usability, reduces errors,
and makes the command-line tools more easily discoverable for users
working in a Linux bash environment.

The completion script dynamically lists available commands and options
by parsing `bitcoin --help` and `bitcoin help`. It also incorporates
the existing bash completions for `bitcoind`, `bitcoin-cli`, and
`bitcoin-tx`, depending on the argument provided (node, rpc, or tx).
This ensures that all relevant completions are available seamlessly
through a single interface without modifying core functionality.

No functional changes to core code are introduced; this is an optional
enhancement placed under `contrib/` for easy installation and use.

39668f1eeb

caesrcd force-pushed on Mar 5, 2026

caesrcd requested review from willcl-ark on Mar 6, 2026

willcl-ark commented at 9:53 PM on March 13, 2026: member

I ran this through shellcheck:

❯ shellcheck contrib/completions/bash/bitcoin.bash

In contrib/completions/bash/bitcoin.bash line 13:
    if ! declare -F $func >/dev/null; then
                    ^---^ SC2086 (info): Double quote to prevent globbing and word splitting.

Did you mean:
    if ! declare -F "$func" >/dev/null; then


In contrib/completions/bash/bitcoin.bash line 17:
        [ -n "$file" ] && source "$file" || return 0
                                 ^-----^ SC1090 (warning): ShellCheck can't follow non-constant source. Use a directive to specify location.


In contrib/completions/bash/bitcoin.bash line 24:
    COMP_LINE="${COMP_WORDS[@]}"
              ^----------------^ SC2124 (warning): Assigning an array to a string! Assign as array, or use * instead of @ to concatenate.


In contrib/completions/bash/bitcoin.bash line 30:
    local cur prev words cword
              ^--^ SC2034 (warning): prev appears unused. Verify use (or export if used externally).


In contrib/completions/bash/bitcoin.bash line 81:
            COMPREPLY=( $( compgen -W "$options $commands" -- "$cur" ) )
                        ^-- SC2207 (warning): Prefer mapfile or read -a to split command output (or quote to avoid splitting).


In contrib/completions/bash/bitcoin.bash line 84:
            if [[ $COMPREPLY == *= ]]; then
                  ^--------^ SC2128 (warning): Expanding an array without an index only gives the first element.

I think we might want to address L13, and perhaps L24 is "more correct" after all? The others look like false positives to me.

caesrcd commented at 12:00 AM on March 14, 2026: contributor

I think we might want to address L13, and perhaps L24 is "more correct" after all? The others look like false positives to me.

L13 is likely a false positive. The assigned value is already defined in the _bitcoin function in this script and only contains single-word values without spaces.

As for L24, I also believe this is a false positive since both approaches result in the same final behavior.

willcl-ark approved

willcl-ark commented at 12:24 PM on March 16, 2026: member

ACK 39668f1eebd1be06cc3429a7e37266e7804ec223

This seems OK now.

The PR description might be updated to reflect that it also wraps bitcoin gui (as well as node), but otherwise LGTM

DrahtBot requested review from epcgrs on Mar 16, 2026

BrandonOdiwuor commented at 12:49 PM on April 7, 2026: contributor

Tested ACK 39668f1eebd1be06cc3429a7e37266e7804ec223

Tested the bash completions for the new unified bitcoin command on Ubuntu 24.04 and everything works exactly as expected

sample commands tested: <img width="1759" height="929" alt="Image" src="https://github.com/user-attachments/assets/b6e467e6-64cb-4e55-8def-eaf4407c9b8e" />

fanquake merged this on Apr 7, 2026

fanquake closed this on Apr 7, 2026