contrib: Add bash completion for new bitcoin command #33385

pull caesrcd wants to merge 1 commits into bitcoin:master from caesrcd:bash-completion changing 1 files +100 −0
  1. caesrcd commented at 3:34 pm on September 13, 2025: none

    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.
  2. DrahtBot added the label Scripts and tools on Sep 13, 2025
  3. DrahtBot closed this on Sep 13, 2025
  4. 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
    Stale ACK epcgrs

    If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.

    Conflicts

    No conflicts as of last run.

  5. fanquake reopened this on Sep 13, 2025
  6. caesrcd force-pushed on Sep 14, 2025
  7. bitcoin deleted a comment on Sep 15, 2025
  8. caesrcd renamed this:
    contrib: add bash completion for new bitcoin command
    contrib: Add bash completion for new bitcoin command
    on Sep 16, 2025
  9. 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

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

    ACK b5d45f0

  11. prusnak commented at 6:51 am on October 13, 2025: contributor
    ISTM “bitcoin test” is not covered
  12. caesrcd commented at 11:56 am on October 13, 2025: none

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

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

    0Copyright (c) 2026-present The Bitcoin Core developers
    caesrcd commented at 12:47 pm on March 4, 2026:
    Done
  14. 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:

     0bitcoin help
 1Usage: bitcoin [OPTIONS] COMMAND...
 2
 3Options:
 4  -m, --multiprocess     Run multiprocess binaries bitcoin-node, bitcoin-gui.
 5  -M, --monolithic       Run monolithic binaries bitcoind, bitcoin-qt. (Default behavior)
 6  -v, --version          Show version information
 7  -h, --help             Show full help message
 8
 9Commands:
10  gui [ARGS]     Start GUI, equivalent to running 'bitcoin-qt [ARGS]' or 'bitcoin-gui [ARGS]'.
11  node [ARGS]    Start node, equivalent to running 'bitcoind [ARGS]' or 'bitcoin-node [ARGS]'.
12  rpc [ARGS]     Call RPC method, equivalent to running 'bitcoin-cli -named [ARGS]'.
13  wallet [ARGS]  Call wallet command, equivalent to running 'bitcoin-wallet [ARGS]'.
14  tx [ARGS]      Manipulate hex-encoded transactions, equivalent to running 'bitcoin-tx [ARGS]'.
15  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:

    0src/core/bitcoin on  pr-33385 [$?] via △ v4.1.2 via 🐍 v3.13.11 via ❄️  impure (nix-shell-env)
1❯ ./build/bin/bitcoin -m tx
2Bitcoin Core bitcoin-tx utility version v30.99.0-b5d45f060161
3
4The 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.
  15. 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.
  16. 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: 
    0            # only parse help if sensible
    caesrcd commented at 1:47 pm on March 4, 2026:
    Done
  17. 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.
  18. willcl-ark changes_requested
  19. 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:

     0[nix-shell:~/src/core/bitcoin]$ source contrib/completions/bash/bitcoin.bash
 1
 2[nix-shell:~/src/core/bitcoin]$ bitcoin
 3bench           gui             help            --multiprocess  rpc             test-gui        --version
 4chainstate      --help          --monolithic    node            test            tx              wallet
 5
 6[nix-shell:~/src/core/bitcoin]$ bitcoin --
 7--help          --monolithic    --multiprocess  --version
 8
 9[nix-shell:~/src/core/bitcoin]$ bitcoin node -
10Display all 136 possibilities? (y or n)
11
12[nix-shell:~/src/core/bitcoin]$ bitcoin node -data
13-datacarrier      -datacarriersize  -datadir=
14
15[nix-shell:~/src/core/bitcoin]$ bitcoin node -datadir=
16build/       ci/          cmake/       depends/     .git/        .ruff_cache/ src/         .tx/
17.cache/      .claude/     contrib/     doc/         .github/     share/       test/
18
19[nix-shell:~/src/core/bitcoin]$ bitcoin rpc
20Display all 181 possibilities? (y or n)
21
22[nix-shell:~/src/core/bitcoin]$ bitcoin rpc getblock
23getblock           getblockcount      getblockfrompeer   getblockheader     getblocktemplate
24getblockchaininfo  getblockfilter     getblockhash       getblockstats
25
26[nix-shell:~/src/core/bitcoin]$ bitcoin tx -
27-chain=<chain>    -help             -signet           -signetseednode   -testnet4         -version
28-create           -json             -signetchallenge  -testnet          -txid
29
30[nix-shell:~/src/core/bitcoin]$ bitcoin tx -create
31delin=         in=            locktime=      outaddr=       outmultisig=   outscript=     set=
32delout=        load=          nversion=      outdata=       outpubkey=     replaceable(=  sign=
33
34[nix-shell:~/src/core/bitcoin]$ bitcoin -m rpc
35bench           gui             help            --multiprocess  rpc             test-gui        --version
36chainstate      --help          --monolithic    node            test            tx              wallet
37
38[nix-shell:~/src/core/bitcoin]$ bitcoin -m tx
39bench           gui             help            --multiprocess  rpc             test-gui        --version
40chainstate      --help          --monolithic    node            test            tx              wallet
41
42[nix-shell:~/src/core/bitcoin]$ bitcoin --multiprocess node
43bench           gui             help            --multiprocess  rpc             test-gui        --version
44chainstate      --help          --monolithic    node            test            tx              wallet
45
46[nix-shell:~/src/core/bitcoin]$ bitcoin guix
47bench           gui             help            --multiprocess  rpc             test-gui        --version
48chainstate      --help          --monolithic    node            test            tx              wallet
49
50[nix-shell:~/src/core/bitcoin]$ bitcoin gui
51bench           gui             help            --multiprocess  rpc             test-gui        --version
52chainstate      --help          --monolithic    node            test            tx              wallet
  20. caesrcd force-pushed on Mar 4, 2026
  21. caesrcd commented at 1:46 pm on March 4, 2026: none
    Rebased
  22. caesrcd requested review from willcl-ark on Mar 4, 2026
  23. 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:

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

    0    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.
  24. 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:

    0        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.
  25. 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:

    0    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.
  26. willcl-ark changes_requested
  27. 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 :)

  28. 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
  29. caesrcd force-pushed on Mar 5, 2026
  30. caesrcd requested review from willcl-ark on Mar 6, 2026
  31. willcl-ark commented at 9:53 pm on March 13, 2026: member

    I ran this through shellcheck:

     0❯ shellcheck contrib/completions/bash/bitcoin.bash
 1
 2In contrib/completions/bash/bitcoin.bash line 13:
 3    if ! declare -F $func >/dev/null; then
 4                    ^---^ SC2086 (info): Double quote to prevent globbing and word splitting.
 5
 6Did you mean:
 7    if ! declare -F "$func" >/dev/null; then
 8
 9
10In contrib/completions/bash/bitcoin.bash line 17:
11        [ -n "$file" ] && source "$file" || return 0
12                                 ^-----^ SC1090 (warning): ShellCheck can't follow non-constant source. Use a directive to specify location.
13
14
15In contrib/completions/bash/bitcoin.bash line 24:
16    COMP_LINE="${COMP_WORDS[@]}"
17              ^----------------^ SC2124 (warning): Assigning an array to a string! Assign as array, or use * instead of @ to concatenate.
18
19
20In contrib/completions/bash/bitcoin.bash line 30:
21    local cur prev words cword
22              ^--^ SC2034 (warning): prev appears unused. Verify use (or export if used externally).
23
24
25In contrib/completions/bash/bitcoin.bash line 81:
26            COMPREPLY=( $( compgen -W "$options $commands" -- "$cur" ) )
27                        ^-- SC2207 (warning): Prefer mapfile or read -a to split command output (or quote to avoid splitting).
28
29
30In contrib/completions/bash/bitcoin.bash line 84:
31            if [[ $COMPREPLY == *= ]]; then
32                  ^--------^ 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.

  32. caesrcd commented at 0:00 am on March 14, 2026: none

    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.

  33. willcl-ark approved
  34. 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

  35. DrahtBot requested review from epcgrs on Mar 16, 2026


caesrcd DrahtBot epcgrs prusnak willcl-ark


epcgrs

Labels
Scripts and tools

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-03-23 06:13 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me