Getting started with SecretHub

This guide will help you get up and running with the SecretHub CLI in minutes. It’s meant to be sweet and short:

  1. Install the SecretHub CLI
  2. Sign up for a SecretHub account
  3. Your first secret
  4. Consume secrets in your application
  5. Check audit logs
  6. Next steps

For full reference, check out the CLI reference docs.

Getting help

Come chat with us on Discord or email us at support@secrethub.io


Step 1: 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: https://github.com/secrethub/secrethub-cli, but we also provide some handy installation methods:

Mac OSX

To install the CLI using Homebrew, run:

brew install secrethub/tools/secrethub-cli

Download the latest Darwin amd64 release.

To install, extract it to a directory of your choosing, for example:

mkdir -p /usr/local/secrethub
tar -C /usr/local/secrethub -xzf secrethub-vx.x.x-os-architecture.tar.gz

Note: depending on your OS configuration, you may need root privileges 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, for example:

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

Linux

To install the CLI with apt-get, add the SecretHub repository to your sources.list:

echo "deb [trusted=yes] https://apt.secrethub.io stable main" > /etc/apt/sources.list.d/secrethub.sources.list && apt-get update

Then, use apt-get install to install the CLI:

apt-get install -y secrethub-cli

Shorthand

You can also use this one-liner instead:

curl https://apt.secrethub.io | bash

To install the CLI on Debian/Ubuntu, download the latest Debian amd64 release:

curl -sSL https://github.com/secrethub/secrethub-cli/releases/download/v0.31.0/secrethub-v0.31.0-linux-amd64.deb -o secrethub-v0.31.0-linux-amd64.deb

Then, use dpkg to install the .deb file:

dpkg -i secrethub-v0.31.0-linux-amd64.deb

You can delete the .deb file afterwards:

rm secrethub-v0.31.0-linux-amd64.deb

For other architectures, see the complete list of CLI releases.

To install the CLI using yum, first add the SecretHub repo to your /etc/yum/repos.d:

curl https://yum.secrethub.io/secrethub.repo -o /etc/yum/repos.d/secrethub.repo --create-dirs

Then, install the CLI like any other yum package:

yum install secrethub-cli

Shorthand

You can also use this one-liner instead:

curl https://yum.secrethub.io | bash

Or you can link to the GitHub release directly, but you won’t be able to automatically yum update later on:

yum install https://github.com/secrethub/secrethub-cli/releases/download/v0.31.0/secrethub-v0.31.0-linux-amd64.rpm

You can install the CLI from our Alpine repository using this one-liner:

apk add --repository https://alpine.secrethub.io/alpine/edge/main --allow-untrusted secrethub-cli

To install the CLI using Snapcraft, run:

snap install secrethub-cli

Sandboxing

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

Download the latest amd64 release. For other architectures, see the complete list of CLI releases.

To install, extract it to a directory of your choosing, for example:

mkdir -p /usr/local/secrethub
tar -C /usr/local/secrethub -xzf secrethub-vx.x.x-os-architecture.tar.gz

Note: depending on your OS configuration, you may need root privileges 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, for example:

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

Windows

On Windows, you can install the CLI using a standard Windows installer. Download the latest amd64 .msi file and follow the installation wizard.

For other architectures, see the complete list of CLI releases.

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

scoop bucket add secrethub https://github.com/secrethub/scoop-secrethub

Afterwards, run this to actually install the CLI:

scoop install secrethub-cli

To download and install the secrethub CLI, run the following in Powershell as an Administrator:

iwr https://get.secrethub.io/windows | iex

And you’re done.

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:

(New-Object System.Net.WebClient).DownloadString("https://get.secrethub.io/windows") | iex

Download the latest amd64 release. For other architectures, see the complete list of CLI releases.

To install, extract it to a directory of your choosing and ensure the directory is on your PATH.

Other

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.

We will add more package managers soon.

Some that are on our whishlist:

  • apt-get
  • choco
  • pacman

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.

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

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

Step 2: Sign up for a SecretHub account

Now that the secrethub CLI is installed on your operating system, let’s create an account. Personal developer accounts are free without limits, so run the signup command and claim yours:

secrethub signup

You now have your very own SecretHub account!

Enter your username below to automatically fill it in the upcoming example code:


Step 3: Your first secret

On signup, a start repository has been created in your workspace. You can read your first secret with:

secrethub read your-username/start/hello

Secrets are automatically versioned so you’ll never accidentally overwrite a secret. You can access a specific version of a secret by appending the version number to the path, e.g. :1. When no version number is given, it defaults to :latest.

You can write a new version of the secret with:

secrethub write your-username/start/hello

Step 4: Consume secrets in your application

In this guide we’ll use environment variables to integrate SecretHub with your application. Checkout our other integrations for more options such as (config) files, Terraform and Ansible.

Pass secrets as environment variables

Many applications that follow the popular 12-Factor App guidelines source their secrets from the environment and those secrets need to be managed too.

That’s where the run command comes in:

secrethub run [options] -- <command>

The run command runs a program and passes environment variables to it as defined in an Environment File with the .env extension.

For example, the following secrethub.env can be used to inject your database credentials into a server application:

# Static values
DB_HOST     = localhost
# Secrets
DB_USER     = {{ $username/start/db/user }}
DB_PASSWORD = {{ $username/start/db/password }}

Everything between {{ and }} is treated as a path to a secret. Also, all variables (starting with a $) are replaced by their values as specified with --var name=value flags.

To demonstrate the result, we will use this Environment File to run the printenv command. Because we use secrethub.env as a filename, it will automatically detected by the CLI. So we can just run:

secrethub run --var username=your-username --no-masking -- printenv

As you can see, the printed output contains the specified environment variables:

[...]
DB_HOST=localhost:5432
DB_USER=example_db_user
DB_PASSWORD=example_password123
[...]

By default, all secret values get filtered from output on stdout and stderr. For this tutorial we use --no-masking to inspect the output. In production this would look like DB_PASSWORD=<redacted by SecretHub>.

See the reference docs for the run command for more detailed examples and explanation of the Environment File syntax.


Step 5: Check audit logs

If you’ve been following along, you’ve likely touched your secrets quite a few times already.

When working in teams, it’s important to be able to track down who has had access to what secret at what point in time. Especially when people leave. That’s what the audit command is for.

For instance, use the following command to track down how the hello secret has been used (and abused) over time:

secrethub audit your-username/start/hello

As you can see, it prints out an audit log for the hello secret.


Next steps

That’s all there is to it. You’ve now mastered the core features of SecretHub!

You can start extracting secrets from source code and inject them securely at runtime with simple building blocks like read, write and run.

To learn more, check out these resources:

Happy coding!