Install the SecretHub CLI

Before creating an account and writing your first secret, you need to install the SecretHub CLI, called secrethub.

The CLI is open source and available on GitHub here:

If you run into issues, check out the troubleshooting section of the reference documentation.

Package managers


To install the CLI using Homebrew, run:

brew install secrethub/tools/secrethub-cli


To install the CLI using Snapcraft, run:

snap install secrethub-cli


Snapcraft sandboxes its apps, so the directory where the SecretHub credential gets stored is not the usual /$HOME/.secrethub, but $HOME/snap/secrethub-cli/<revision>/.secrethub instead. When you snap remove an app, the entire Snap home of the app gets deleted, so make sure you don’t lose your SecretHub credential.

If you want to change this behavior, set the SECRETHUB_CONFIG_DIR environment variable:

export SECRETHUB_CONFIG_DIR=$HOME/.secrethub


To install the CLI using Scoop, first add the SecretHub bucket:

scoop bucket add secrethub

Afterwards, run this to actually install the CLI:

scoop install secrethub-cli

More to come…

We will add more package managers soon.

Manual installation

Official binary distributions are available for the Linux, macOS, and Windows operating systems for both 32-bit (386) and 64-bit (amd64) architectures.

You can download the latest release here.

Linux and macOS

To install the secrethub CLI, download the .tar.gz archive for Linux or macOS (darwin) and extract it e.g. to /usr/local/secrethub:

mkdir -p /usr/local/secrethub
tar -C /usr/local/secrethub -xzf path/to/secrethub.tar.gz

Note: depending on your OS configuration, you may need root priviliges to write to the /usr/local directory.

Ensure the binary is accessible by symlinking to it from a directory that is on your PATH environment variable, e.g. /usr/local/bin:

ln -s /usr/local/secrethub/bin/secrethub /usr/local/bin/secrethub

Alternatively, you can add the /usr/local/secrethub/bin folder to your PATH environment variable.

export PATH=$PATH:/usr/local/secrethub/bin

And you’re done. For more installation options, see the README on GitHub


To download and install the secrethub CLI, run the following one-liner in Powershell:

# Run in Windows Powershell as Administrator
iwr | iex 

And you’re done. For more installation options, see the README on GitHub

Note: this works for Windows Server 2012 R2, Windows 8, and upwards. For older operating systems (e.g. Windows Server 2008 R2), use the equivalent more verbose command:

# Run in Windows Powershell as Administrator
(New-Object System.Net.WebClient).DownloadString("") | iex


You can also choose to run the CLI as an isolated Docker container instead.

docker run -it -v $HOME/.secrethub:/root/.secrethub secrethub/cli

And optionally create an alias for it:

alias secrethub='docker run -it -v $HOME/.secrethub:/root/.secrethub secrethub/cli'

Note: some features of the CLI may not be available by default in Docker, like writing to the clipboard with the --clip flag or piping a secret to the write command.

Verify the CLI is correctly installed

To test your installation, run:

secrethub --version

If all went well, this should print out the version of the SecretHub CLI that was just installed.

Install auto-completion

To install auto-completion for the CLI, run one of the following commands depending on your shell of choice:

# Install bash completion
secrethub --completion-script-bash > /etc/bash_completion.d/secrethub
# Install zsh completion
secrethub --completion-script-zsh > ~/.zsh/completion/secrethub

️️➡️ Next, let’s sign up for a SecretHub account.