Install HCP CLI for Vault Secrets

9min
|
HCP
Vault

Before you can interact with HCP Vault Secrets using the command-line interface (CLI), you will need to install the HCP CLI and configure it for your HCP environment.

Once installed, you can choose to authenticate interactively using your HCP Portal credentials, or non-interactively using a HCP service principal.

Prerequisites

An existing HCP account
Completed the Create a secret in HCP Vault Secrets tutorial
Homebrew installed

Install HCP CLI

The HCP CLI is available for download from releases.hashicorp.com/hcp as a zip archive and via popular package managers. To support HCP Vault secrets, you must use version 0.3.0 or greater.

MacOS users can use Homebrew to install the HCP CLI. Refer to the Homebrew installation instructions if it is not already installed.

Open a new terminal.
Install the HashiCorp tap.
```
$ brew tap hashicorp/tap
```
Install the HCP CLI.
```
$ brew install hashicorp/tap/hcp
```

Verify the installation.

$ hcp
USAGE
  hcp <command> [Optional Flags]
DESCRIPTION
  The HCP Command Line Interface is a unified tool to manage your HCP services.
COMMAND GROUPS
  auth:           Authenticate to HCP.
  iam:            Identity and access management.
  organizations:  Interact with an existing organization.
  profile:        View and edit HCP CLI properties.
  projects:       Create and manage projects.
  waypoint:       Manage Waypoint.
COMMANDS
  version:  Display the HCP CLI version.
GLOBAL FLAGS
  --debug
    Enable debug output.
  --format=FORMAT
    Sets the output format.
  --profile=NAME
    The profile to use. If omitted, the currently selected profile will be used.
  --project=ID
    The HCP Project ID to use. If omitted the current project set in the
    configuration is used.
  --quiet
    Minimizes output.

HashiCorp does not maintain installation binaries using Chocolatey or Scoop. The latest version of the HCP Vault Secrets CLI is available by manual installation.

This example downloads the Windows AMD64 binary using PowerShell. Use a Windows account with appropriate permissions to extract the binary to the Program Files directory and update the PATH.

Launch a PowerShell terminal using Run as Administrator. If prompted, click Yes.

Download the zip archive to the current working directory.

$ Invoke-WebRequest -URI https://releases.hashicorp.com/hcp/0.3.0/hcp_0.3.0_windows_amd64.zip`
   -OutFile hcp_0.3.0_windows_amd64.zip

Unzip the file.

$ Expand-Archive -Path .\hcp_0.3.0_windows_amd64.zip -Destination `C:\Program Files\HashiCorp\hcp\bin\`

Update the $PATH environment variable.

$ $Env:path = $env:path + ";C:\Program Files\HashiCorp\hcp\bin"

Verify the hcp binary is available.

$ hcp
USAGE
  hcp <command> [Optional Flags]
DESCRIPTION
  The HCP Command Line Interface is a unified tool to manage your HCP services.
COMMAND GROUPS
  auth:           Authenticate to HCP.
  iam:            Identity and access management.
  organizations:  Interact with an existing organization.
  profile:        View and edit HCP CLI properties.
  projects:       Create and manage projects.
  waypoint:       Manage Waypoint.
COMMANDS
  version:  Display the HCP CLI version.
GLOBAL FLAGS
  --debug
    Enable debug output.
  --format=FORMAT
    Sets the output format.
  --profile=NAME
    The profile to use. If omitted, the currently selected profile will be used.
  --project=ID
    The HCP Project ID to use. If omitted the current project set in the
    configuration is used.
  --quiet
    Minimizes output.

The installation steps provided were tested on Ubuntu 22.04 and should work on other Debian based distributions that utilize the apt package manager.

Update the apt repository.

$ sudo apt-get update && \
  sudo apt-get install gpg coreutils

Download the HashiCorp GPG key.

$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

Add the HashiCorp repo.

$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

Install the HCP CLI.

$ sudo apt update && sudo apt install hcp -y

Verify the installation.

$ hcp
USAGE
  hcp <command> [Optional Flags]
DESCRIPTION
  The HCP Command Line Interface is a unified tool to manage your HCP services.
COMMAND GROUPS
  auth:           Authenticate to HCP.
  iam:            Identity and access management.
  organizations:  Interact with an existing organization.
  profile:        View and edit HCP CLI properties.
  projects:       Create and manage projects.
  waypoint:       Manage Waypoint.
COMMANDS
  version:  Display the HCP CLI version.
GLOBAL FLAGS
  --debug
    Enable debug output.
  --format=FORMAT
    Sets the output format.
  --profile=NAME
    The profile to use. If omitted, the currently selected profile will be used.
  --project=ID
    The HCP Project ID to use. If omitted the current project set in the
    configuration is used.
  --quiet
    Minimizes output.

The installation steps provided were tested on Amazon Linux 2 and should work on other distributions that utilize the yum package manager.

Update the yum repository.
```
$ sudo yum update
```
Install yum-utils.
```
$ sudo yum install -y yum-utils
```

Add the HashiCorp repository.

Note

Refer to the official packaging guide for the correct RHEL/CentOS or Fedora configuration.

$ curl -fsSL https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo | sudo tee /etc/yum.repos.d/hashicorp.repo

Update the local yum repository.
```
$ sudo yum update
```
Install the HCP CLI.
```
$ sudo yum install hcp -y
```

Verify the installation.

$ hcp
USAGE
  hcp <command> [Optional Flags]
DESCRIPTION
  The HCP Command Line Interface is a unified tool to manage your HCP services.
COMMAND GROUPS
  auth:           Authenticate to HCP.
  iam:            Identity and access management.
  organizations:  Interact with an existing organization.
  profile:        View and edit HCP CLI properties.
  projects:       Create and manage projects.
  waypoint:       Manage Waypoint.
COMMANDS
  version:  Display the HCP CLI version.
GLOBAL FLAGS
  --debug
    Enable debug output.
  --format=FORMAT
    Sets the output format.
  --profile=NAME
    The profile to use. If omitted, the currently selected profile will be used.
  --project=ID
    The HCP Project ID to use. If omitted the current project set in the
    configuration is used.
  --quiet
    Minimizes output.

To install the HCP CLI, find the appropriate package for your system and download it. The hcp CLI is packaged as a zip archive.

After downloading the zip archive, unzip the package. The HCP Vault Secrets binary runs as a single binary named hcp. Any other files in the package can be safely removed and hcp will still function.

The final step is to make sure that the hcp binary is available on the PATH. See this page for instructions on setting the PATH on Linux and Mac. This page contains instructions for setting the PATH on Windows.

Configure the HCP CLI for Vault Secrets

Interactive logins launch a web browser to have you authenticate with your HCP user account through a supported authorization method such as username and password, single sign-on (SSO), or GitHub.

Refer to the HCP Vault Secrets documentation to review HCP roles and permissions.

Log in to HCP Vault Secrets using the interactive login.
```
$ hcp auth login
```
A new browser will open, log into your HCP account. Once complete, your browser will display Login is successful. You may close the browser and return to the command line..

Return to the terminal session.

Example output:

The default web browser has been opened at https://auth.idp.hashicorp.com/oauth2/auth. Please continue the login in the web browser.
Success!
Successfully logged in!

Create a profile.
```
$ hcp profile init --vault-secrets
```

If you are a member of multiple HCP organizations, select the organization you want to use. Use the arrow keys to select the HCP organization.

Example output:

Use the arrow keys to navigate: ↓ ↑ → ←
? Multiple Organizations found please select the one you would like to configure.:
  > vault-edu-org
  hashicorp-education
  hashicorp-edu-org

----- Organization -----
Name:   vault-edu-org
ID:     12cd56-88d2-69fb-8cc1-s3sAm3st
State:  ACTIVE

If you have multiple projects in your HCP organization, select the project you want to use. Use the arrow keys to select the HCP project.

Use the arrow keys to navigate: ↓ ↑ → ←
? Multiple projects found. Please select the one you would like to configure.:
  DevelopmentProject
  > Production

----- Organization -----
Name:        Production
ID:          12cd56-704c-46af-8ba5-mAtr3x
Description:
State:       ACTIVE

The HCP CLI will detect the WebApplication app you created in an earlier tutorial.

$ hcp profile init --vault-secrets
  ✓ Organization with name "hashicorp-edu-org" and ID "12cd56-88d2-69fb-8cc1-s3sAm3st" selected
  ✓ Project with name "ProductionProject" and ID "12cd56-704c-46af-8ba5-mAtr3x" selected
  ✓ App with name "WebApplication" selected

Run hcp vault-secrets secrets list to review the existing secrets.
```
$ hcp vault-secrets secrets list
Name      Latest Version  Created At
username  2               2023-05-24T12:22:18.395Z
```
If you create multiple HCP Vault Secrets apps, you can use the --app command line parameter followed by the name of the app.

Non-interactive logins require the use of an HCP service principal and associated key created at the HCP organization level.

Refer to the HCP Vault Secrets documentation to review HCP roles and permissions.

Open your web browser and log into the HCP Portal.
Select the project where HCP Vault Secrets is configured.
Click Access control (IAM).
Click Service principals.
Click Create service principal.
Enter hcp-vault-secrets-tutorial in the Service principal name textbox.
In the Select service drop-down menu, select Secrets.
In the Select role drop-down menu, select Vault Secrets App Secret Reader.
Click Create service principal.
Click Keys, and click Generate key.
Copy the Client ID.
Return to your terminal and export an environment variable named HCP_CLIENT_ID.
```
$ export HCP_CLIENT_ID=<copied-id>
```
Return to the HCP portal and copy the Client secret.
Return to your terminal and export an environment variable named HCP_CLIENT_SECRET.
```
$ export HCP_CLIENT_SECRET=<copied-secret>
```
Export and environment variable named APP_NAME.
```
$ export APP_NAME=WebApplication
```

Configure the HCP CLI to use the WebApplication app.

$ hcp profile set vault-secrets/app $APP_NAME
✓ Property "vault-secrets/app" updated

Run hcp auth login to complete the authentication process.
```
$ hcp auth login
Successfully logged in!
```
Authentication uses the HCP_CLIENT_ID and HCP_CLIENT_SECRET environment variables for the service principal create earlier.
These variables can also be passed to the HCP CLI for a script or workflow if environment variables are not supported.
Run hcp vault-secrets secrets list to review the existing secrets.
```
$ hcp vault-secrets secrets list
Name      Latest Version  Created At
username  2               2023-05-24T12:22:18.395Z
```
If you create multiple HCP Vault Secrets apps, you can use the --app command line parameter followed by the name of the app.

Next steps

In this tutorial you installed and configured the HCP CLI, and authenticated using the interactive and non interactive methods.

In the next tutorial you will learn how to retrieve a secret using the command line interface (CLI) and API. Using the CLI or API will allow you to automate secret retrieval from HCP Vault Secrets.

Create a secret in HCP Vault Secrets

Retrieve a secret from HCP Vault Secrets