Skip to main content

Shell completion

Prysm's beacon-chain and validator CLIs support shell completion for Bash, Zsh, and Fish shells. Once enabled, you can press TAB to auto-complete subcommands, nested commands, and flags, significantly improving your command-line experience.

Generating completion scripts​

Each binary includes a completion subcommand that generates shell-specific completion scripts.

# Generate the completion script
beacon-chain completion bash

# Or for the validator
validator completion bash

Loading completions​

Temporary (current session only)​

Load completions for the current terminal session:

# Load beacon-chain completions
source <(beacon-chain completion bash)

# Load validator completions
source <(validator completion bash)

Persistent (all future sessions)​

To enable completions automatically in all new terminal sessions, save the completion scripts to the appropriate location for your shell:

# User-local installation (recommended)
mkdir -p ~/.local/share/bash-completion/completions
beacon-chain completion bash > ~/.local/share/bash-completion/completions/beacon-chain
validator completion bash > ~/.local/share/bash-completion/completions/validator
note

The user-local directory requires bash-completion 2.0 or later. On older systems, you may need to install completions to the system-wide /etc/bash_completion.d/ directory as root.

Using completions​

Once completions are loaded, press TAB to see available options:

Command completion​

# Type partial command and press TAB
beacon-chain db<TAB>
# Completes to: beacon-chain db

beacon-chain db <TAB>
# Shows: restore  ...

Flag completion​

# Type -- and press TAB to see all flags
beacon-chain --<TAB>
# Shows: --datadir  --execution-endpoint  --checkpoint-sync-url  ...

# Type partial flag name and press TAB
beacon-chain --exec<TAB>
# Shows: --execution-endpoint  --execution-headers

Contextual completion​

Completions are context-aware. The available suggestions change based on the subcommand you're using:

# Global beacon-chain flags
beacon-chain --<TAB>

# Subcommand-specific flags
beacon-chain db restore --<TAB>

Using with prysm.sh​

If you run Prysm using the prysm.sh script, you can still use completion by first building or downloading the binaries. The completion scripts work with the standalone beacon-chain and validator binaries.

# Example: If using downloaded binaries
./beacon-chain completion bash > ~/.local/share/bash-completion/completions/beacon-chain

How it works​

The shell completion scripts use urfave/cli's built-in completion mechanism. When you press TAB, the shell runs the binary with a hidden --generate-bash-completion flag appended to your current input. The binary returns a list of valid completions for your context, which the shell then presents as suggestions.

This means completions always reflect the current binary's actual flags and commands - they're never out of date.

Troubleshooting​

Completions not working after installation​

  1. Start a new terminal session - Completion scripts are typically loaded when the shell starts

  2. Check the script location - Ensure the completion script is in the correct directory for your shell

  3. Verify bash-completion is installed (Bash only):

    # Debian/Ubuntu
    apt install bash-completion

    # macOS with Homebrew
    brew install bash-completion@2

Zsh completions not loading​

Ensure compinit is called in your ~/.zshrc:

autoload -Uz compinit && compinit

If completions still don't work, try rebuilding the completion cache:

rm -f ~/.zcompdump && compinit

Permission denied errors​

If you get permission errors when installing to system directories, use the user-local installation method instead (see persistent installation above). User-local completions work identically and don't require elevated privileges.