contrib: Add zsh completion scripts

bittoby commented at 11:20 pm on March 23, 2026: none

Add zsh completion scripts for bitcoind, bitcoin-cli, and bitcoin-tx using zsh’s native compdef system.

Bash and fish completions already exist, but zsh has no equivalent. Since zsh is the default shell on macOS and widely used on Linux, this fills the gap.

Closes #33404. Continues the work started in #33402.

The scripts are under contrib/completions/zsh/ and match the existing bash completions in functionality:

_bitcoind - option completion with file/directory path handling
_bitcoin-cli - RPC command and option completion with context-sensitive arguments (booleans, sighash types, subcommands)
_bitcoin-tx - option and command completion with file path handling

All completions dynamically parse -help output rather than hardcoding option lists.

How to test

Copy the scripts to a directory in your zsh fpath and start a new shell:

mkdir -p ~/.zsh/completions
cp contrib/completions/zsh/_bitcoin* ~/.zsh/completions/
# add to .zshrc: fpath=(~/.zsh/completions $fpath) && autoload -Uz compinit && compinit

Then verify tab completion works:

bitcoind -<TAB>                        # shows options from -help
bitcoind -datadir=<TAB>                # completes directories
bitcoin-cli <TAB>                      # shows options and RPC commands
bitcoin-cli getblock <hash> <TAB>      # suggests true/false
bitcoin-tx -create <TAB>               # shows transaction commands

DrahtBot added the label Scripts and tools on Mar 23, 2026

DrahtBot commented at 11:21 pm on March 23, 2026: contributor

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

Reviews

See the guideline for information on the review process. A summary of reviews will appear here.

Conflicts

Reviewers, this pull request conflicts with the following ones:

#33747 (contrib: zsh and fish completions for bitcoin wrapper executable by hulxv)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

bittoby commented at 11:29 am on March 25, 2026: none

@mstampfer @maflcko Could you please review this PR when you have time? Welcome to any feedbacks! thank you

mstampfer commented at 11:16 am on March 27, 2026: none

Will zsh completion scripts be made for bitcoin-wallet, bitcoin-util, bitcoin-qt? Fish completions exist for these but no zsh equivalents exist.

mstampfer commented at 11:17 am on March 27, 2026: none

Copyright year — Files say 2025-present but this is being submitted in 2026. Should be 2026-present

mstampfer commented at 11:19 am on March 27, 2026: none

_bitcoin-tx -help<TAB> incorrectly yields top level flags

bittoby commented at 12:47 pm on March 27, 2026: none

@mstampfer Thanks for your feedback. Good point!. I updated all. please review again.

maflcko commented at 12:55 pm on March 27, 2026: member

Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

bittoby force-pushed on Mar 27, 2026

bittoby commented at 1:00 pm on March 27, 2026: none

@maflcko Thanks. I squashed my commits

mstampfer commented at 1:15 pm on March 27, 2026: none

I should have made this clearer. All flags other than -create incorrectly yield top level flags. e.g. _bitcoin-tx -json<TAB>

bittoby commented at 1:23 pm on March 27, 2026: none

I should have made this clearer. All flags other than -create incorrectly yield top level flags. e.g. _bitcoin-tx -json

So you mean when I type bitcoin-tx -json <TAB>, nothing should appear?

bittoby commented at 1:25 pm on March 27, 2026: none

bitcoin-tx <TAB> - show options (-json, -create, -help, etc.) bitcoin-tx -create <TAB> - show commands (delin=, set=, etc.) bitcoin-tx -json <TAB> - show nothing bitcoin-tx -help <TAB> - show nothing

Is that right approach?

mstampfer commented at 1:45 pm on March 27, 2026: none

Correction : bitcoin-tx <TAB> - show options (-json, -create, -help, etc.) bitcoin-tx -create <TAB> - show commands (delin=, set=, etc.) bitcoin-tx -create -json <TAB> - show options (delin=, set=, etc.) bitcoin-tx -create -txid <TAB> - show commands (delin=, set=, etc.) bitcoin-tx -help <TAB> - show nothing bitcoin-tx -version <TAB> - show nothing

bittoby force-pushed on Mar 27, 2026

bittoby commented at 1:57 pm on March 27, 2026: none

@mstampfer Thanks. I updated. please test again. 👍

mstampfer commented at 2:24 pm on March 27, 2026: none

bitcoin-tx -create -json<TAB> doesn’t seem to work. No options or commands are given

Simplifying the above, after -create at the first position, the completion should offer both options and commands. bitcoin-tx -create -json<TAB> -chain= -create -help… delin= delout= in=….

e.g. if $has_create; then # show both commands AND options …cmds… …opts…

bittoby commented at 2:25 pm on March 27, 2026: none

bitcoin-tx -create -json doesn’t seem to work. No options or commands are given

Simplifying the above, after -create at the first position, the completion should offer both options and commands. bitcoin-tx -create -json -chain= -create -help… delin= delout= in=….

e.g. if $has_create; then # show both commands AND options …cmds… …opts…

Huh… weired. I will check again

contrib: Add zsh completion scripts for Bitcoin Core command-line tools be0b7233eb

bittoby force-pushed on Mar 27, 2026

bittoby commented at 2:54 pm on March 27, 2026: none

bitcoin-tx -create -json doesn’t seem to work. No options or commands are given

Simplifying the above, after -create at the first position, the completion should offer both options and commands. bitcoin-tx -create -json -chain= -create -help… delin= delout= in=….

e.g. if $has_create; then # show both commands AND options …cmds… …opts…

Pls test again now. It works well

mstampfer commented at 3:03 pm on March 27, 2026: none

looks good

bittoby commented at 3:27 pm on March 30, 2026: none

@maflcko I hope you had a great weekend. Could you please review my pr and give me any feedback? Thanks

maflcko commented at 3:36 pm on March 30, 2026: member

I am not using zsh, so I am not qualified to review this, sorry

bittoby commented at 3:43 pm on March 30, 2026: none

I am not using zsh, so I am not qualified to review this, sorry

Thanks for replying. so who can review my pr? @mstampfer already review this PR.

contrib: Add zsh completion scripts #34906

How to test

Reviews

Conflicts