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

First download the latest 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 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, for example:

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

Linux

To install the CLI using Snapcraft, run:

snap install secrethub-cli

To install the CLI using [Snapcraft][snapcraft]{:target=”_blank”}, 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

To install the CLI using apk, you first need to add the SecretHub public key to your /etc/apk/keys:

apk add curl
curl -fsSLo /etc/apk/keys/secrethub.rsa.pub https://alpine.secrethub.io/pub

Then, add the SecretHub repo to /etc/apk/repositories:

echo "https://alpine.secrethub.io/alpine/edge/main" >> /etc/apk/repositories

Finally, you can install the CLI as any other apk package:

apk add --update secrethub-cli

First download the latest 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 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, for example:

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

Windows

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

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:

  • yum
  • 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, so run the signup command and claim yours:

secrethub signup

You now have your very own SecretHub account!

A credential is placed in the .secrethub folder in your home directory, which will be used to authorize and to locally encrypt and decrypt your secrets, so that we will never have the ability to see them.

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

Just like before, 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-world secret has been used (and abused) over time:

secrethub audit your-username/start/hello-world

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

You can use the --timestamp flag to show timestamps instead of human readable durations.


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!