Quickstart

In the following steps, we explore how to use the KMS CLI to fetch back environment variables from Hanzo KMS and inject them into your local development process.

If you prefer learning by watching, you can follow along our step-by-step video tutorial here.

Start by running the kms login command to authenticate with Hanzo KMS.

kms login

If you are in a containerized environment such as WSL 2 or Codespaces, run kms login -i to avoid browser based login

Next, navigate to your project and initialize Hanzo KMS.

# navigate to your project
cd /path/to/project

# initialize kms
kms init

The kms init command creates a .kms.json file, containing local project settings, at the location where the command is executed.

The .kms.json file does not contain any sensitive data, so you may commit it to your git repository.

Finally, pass environment variables from Hanzo KMS into your application.

kms run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

# example with node (nodemon)
kms run --env=staging --path=/apps/spotify -- nodemon index.js

# example with flask
kms run --env=prod --path=/apps/backend -- flask run

# example with spring boot - maven
kms run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet

Custom aliases can utilize secrets from Hanzo KMS. Suppose there is a custom alias yd in custom.sh that runs yarn dev and needs the secrets provided by Hanzo KMS.

#!/bin/sh

yd() {
  yarn dev
}

To make the secrets available from Hanzo KMS to yd, you can run the following command:

kms run --env=prod --path=/apps/reddit --command="source custom.sh && yd"

View all available options for run command here

In the following steps, we explore how to use the KMS CLI in a non-local development scenario to fetch back environment variables and export them to a file.

Follow the steps listed here to create a machine identity and obtain a client ID and client secret for it.

Run the following command to authenticate with Hanzo KMS using the client ID and client secret credentials from step 1 and set the INFISICAL_TOKEN environment variable to the retrieved access token.

export INFISICAL_TOKEN=$(kms login --method=universal-auth --client-id=<identity-client-id> --client-secret=<identity-client-secret> --silent --plain) # --plain flag will output only the token, so it can be fed to an environment variable. --silent will disable any update messages.

The CLI is configured to look out for the INFISICAL_TOKEN environment variable, so going forward any command used will be authenticated.

Alternatively, assuming you have an access token on hand, you can also pass it directly to the CLI using the --token flag in conjunction with other CLI commands.

Keep in mind that the machine identity access token has a limited lifetime. It is recommended to use it only for the duration of the task at hand. You can refresh the token if needed.

Finally, export the environment variables from Hanzo KMS to a file of choice.

# export variables to a .env file (with export keyword)
kms export --format=dotenv-export > .env

# export variables to a YAML file
kms export --format=yaml > secrets.yaml

Starting with CLI version v0.4.0, you can now choose to log in via Hanzo KMS Cloud (US/EU) or your own self-hosted instance by simply running kms login and following the on-screen instructions — no need to manually set the INFISICAL_API_URL environment variable.

For versions prior to v0.4.0, the CLI defaults to US Cloud. To connect to EU Cloud or a self-hosted instance, set the INFISICAL_API_URL environment variable to https://eu.kms.hanzo.ai or your custom URL.

Domain Configuration

Important: If you're not using interactive login, you must configure the domain for all CLI commands.

The CLI defaults to US Cloud (https://app.kms.hanzo.ai). To connect to EU Cloud (https://eu.kms.hanzo.ai) or a self-hosted instance, you must configure the domain in one of the following ways:

• Use the INFISICAL_API_URL environment variable
• Use the --domain flag on every command

The easiest way to ensure all CLI commands use the correct domain is to set the INFISICAL_API_URL environment variable. This applies the domain setting globally to all commands:

# Linux/MacOS
export INFISICAL_API_URL="https://your-domain.kms.hanzo.ai"

# Windows PowerShell
setx INFISICAL_API_URL "https://your-domain.kms.hanzo.ai"

Once set, all subsequent CLI commands will automatically use this domain:

# Login with the domain
kms login --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain

# All other commands will also use the same domain automatically
kms secrets --projectId <id> --env dev

The --domain flag can be used to set the domain for a single command. This applies the domain setting to the command only:

# Login with domain
kms login --domain="https://your-domain.kms.hanzo.ai" --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain

# All subsequent commands must also include --domain
kms secrets --domain="https://your-domain.kms.hanzo.ai" --projectId=<id> --env=dev

If you use --domain during login but forget to include it on subsequent commands, you may encounter authentication errors.

Custom Request Headers

The KMS CLI supports custom HTTP headers for requests to servers protected by authentication services such as Cloudflare Access. Configure these headers using the INFISICAL_CUSTOM_HEADERS environment variable:

# Syntax: headername1=headervalue1 headername2=headervalue2
export INFISICAL_CUSTOM_HEADERS="Access-Client-Id=your-client-id Access-Client-Secret=your-client-secret"

# Execute Hanzo KMS commands after setting the environment variable
kms secrets

This functionality enables secure interaction with Hanzo KMS instances that require specific authentication headers.

History

$HOME/.profile is pretty common but, you could place it under $HOME/.profile.d/kms.sh or any profile file run at login

cat <<EOF >> $HOME/.profile && source $HOME/.profile

# Ignoring specific KMS CLI commands
DEFAULT_HISTIGNORE=$HISTIGNORE
export HISTIGNORE="*kms secrets set*:$DEFAULT_HISTIGNORE"
EOF

If you're on WSL, then you can use the Unix/Linux method.

Here's some documentation about how to clear the terminal history, in PowerShell and CMD

FAQ

Yes. The CLI is set to connect to Hanzo KMS US Cloud by default, but if you're using EU Cloud or a self-hosted instance you can configure the domain for all CLI commands.

Method 1: Use the updated CLI (v0.4.0+)

Beginning with CLI version V0.4.0, you can choose between logging in through Hanzo KMS US Cloud, EU Cloud, or your own self-hosted instance. Simply execute the kms login command and follow the on-screen instructions.

Method 2: Export environment variable

You can point the CLI to the self-hosted Hanzo KMS instance by exporting the environment variable INFISICAL_API_URL in your terminal.

# Set the API URL
export INFISICAL_API_URL="https://your-self-hosted-kms.hanzo.ai"

# For EU Cloud
export INFISICAL_API_URL="https://eu.kms.hanzo.ai"

# Remove the setting
unset INFISICAL_API_URL

# Set the API URL
setx INFISICAL_API_URL "https://your-self-hosted-kms.hanzo.ai"

# For EU Cloud
setx INFISICAL_API_URL "https://eu.kms.hanzo.ai"

# Remove the setting
setx INFISICAL_API_URL ""

# NOTE: Once set, please restart powershell for the change to take effect

Method 3: Set manually on every command

If you prefer not to use an environment variable, you must include the --domain flag on every CLI command you run:

# Login with domain
kms login --domain="https://your-domain.kms.hanzo.ai" --method=oidc-auth --jwt $JWT

# All subsequent commands must also include --domain
kms secrets --domain="https://your-self-hosted-kms.hanzo.ai" --projectId <id> --env dev
kms export --domain="https://your-self-hosted-kms.hanzo.ai" --format=dotenv-export

Best Practice: Use INFISICAL_API_URL environment variable (Method 2) to avoid having to remember the --domain flag on every command. This is especially important in CI/CD pipelines and automation scripts.

To use Hanzo KMS for non local development scenarios, please create a service token. The service token will allow you to authenticate and interact with Hanzo KMS. Once you have created a service token with the required permissions, you’ll need to feed the token to the CLI.

  kms export --token=<service-token>
  kms secrets --token=<service-token>
  kms run --token=<service-token> -- npm run dev

Pass via shell environment variable

The CLI is configured to look for an environment variable named INFISICAL_TOKEN. If set, it’ll attempt to use it for authentication.

  export INFISICAL_TOKEN=<service-token>