SecretHub logo Get Started with SecretHub

This guide will help you get up and running with your free SecretHub account in minutes. It’s short and sweet.

The first thing to do is to install the SecretHub CLI. To bring you end-to-end encryption, you’ll need the CLI to generate a key.

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

Step 1: Install the SecretHub CLI

Before creating an account and writing your first secret, install the secrethub CLI.

It’s open source and available on GitHub, but we also provide some handy installation methods:

MacOS

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 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.37.0/secrethub-v0.37.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 on Debian/Ubuntu, download the latest Debian amd64 release and install it with dpkg:

curl -sLJO https://deb.secrethub.io/amd64
dpkg -i secrethub-cli-amd64.deb
rm secrethub-cli-amd64.deb

To update the CLI, you can just re-run this command.

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

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.

Windows 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

To build the CLI yourself, you just need Go and GNU Make installed:

git clone https://github.com/secrethub/secrethub-cli
cd secrethub-cli
make build

You can then place the secrethub binary in a directory on your PATH, e.g. /usr/bin/.

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:

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


Step 2: Sign up for a free 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

Every account comes with a personal workspace. To help you find your way, we’ve already created a sample secret. To read a secret, run:

secrethub read your-username/start/hello

You can write a new version of the secret with:

secrethub write 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.


Step 4: Consume secrets in your application

There are many way to provision an application with the secrets it needs. One common way is through environment variables, which you’ll see below. For a full list of integrations, see integrations.

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.

To see the mechanism in action, the SecretHub CLI comes packed with a demo application. This application serves a web page and tries to connect to https://demo.secrethub.io/api/v1/basic-auth using credentials provided in the environment (DEMO_USERNAME and DEMO_PASSWORD).

First, try to run the app locally without setting the username and password:

secrethub demo serve

A web page will now be served at http://localhost:8080, but if you visit it, you’ll see that it shows an error because it’s missing the username and password.

To get the demo application to work correctly, you’ll need to provide a username and password. You wouldn’t want to have those scattered around in plaintext, so let’s store those on SecretHub instead and use secrethub run to inject them at runtime.

Here’s a nice shortcut to auto-generate the values for you at your-username/demo:

secrethub demo init

Next, instead of populating environment variables with plaintext secrets, use secret references:

export DEMO_USERNAME=secrethub://your-username/demo/username
export DEMO_PASSWORD=secrethub://your-username/demo/password

Then, wrap the app start command in secrethub run:

secrethub run -- secrethub demo serve

The referenced secrets will now automatically get fetched, decrypted and injected as environment variables to the app.

If you visit http://localhost:8080 again, you’ll see that the red cross got replaced by a green checkmark. The wisdom that was hidden in the Demo API has now been revealed!


Step 5: Check audit logs

By now, you’ve touched your secrets a few times already.

When working in teams, it’s important to be able to track down who accessed which secrets at which point in time. 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 Up

🚀 Deploy an Application with Secrets