kms/docs/cli/usage.mdx

---
title: "Quickstart"
description: "Manage secrets with KMS CLI"
---

The CLI is designed for a variety of secret management applications ranging from local development to CI/CD and production scenarios.

<Tabs>
  <Tab title="Local development">
    In the following steps, we explore how to use the KMS CLI to fetch back environment variables from KMS
    and inject them into your local development process.
    
    <Note>
    If you prefer learning by watching, you can follow along our step-by-step video tutorial [here](https://www.youtube.com/watch?v=EzDQC7nY3YY).
    </Note>

    <Steps>
      <Step title="Log in with the CLI">
        Start by running the `hanzo-kms login` command to authenticate with KMS.

        ```bash
        hanzo-kms login
        ```
        <Note>
          If you are in a containerized environment such as WSL 2 or Codespaces, run `hanzo-kms login -i` to avoid browser based login
        </Note>
      </Step>
      <Step title="Initialize KMS for your project">
        Next, navigate to your project and initialize KMS.

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

        # initialize kms
        hanzo-kms init
        ```

        The `hanzo-kms init` command creates a `.kms.json` file, containing [local project settings](./project-config), at the location where the command is executed.

        <Note>
          The `.kms.json` file does not contain any sensitive data, so you may commit it to your git repository.
        </Note>
      </Step>
      <Step title="Inject environment variables">
        Finally, pass environment variables from KMS into your application.

        <Tabs>
          <Tab title="Feed secrets to your application">
            ```bash
            hanzo-kms run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

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

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

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

          </Tab>
          <Tab title="Feed secrets via custom aliases (advanced)">
            Custom aliases can utilize secrets from KMS. Suppose there is a custom alias `yd` in `custom.sh` that runs `yarn dev` and needs the secrets provided by KMS.
            ```bash
            #!/bin/sh

            yd() {
              yarn dev
            }
            ```

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

            ```bash
            hanzo-kms run --env=prod --path=/apps/reddit --command="source custom.sh && yd"
            ```
          </Tab>
        </Tabs>

        View all available options for `run` command [here](./commands/run)
      </Step>
    </Steps>

  </Tab>

  <Tab title="Staging, production & all other use cases">
    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.
    <Steps>
      <Step title="Create a machine identity and obtain credentials for it">
        Follow the steps listed [here](/documentation/platform/identities/universal-auth) to create a machine identity and obtain a **client ID** and **client secret** for it.
      </Step>
      <Step title="Obtain a machine identity access token">
        Run the following command to authenticate with KMS using the **client ID** and **client secret** credentials from step 1 and set the `KMS_TOKEN` environment variable to the retrieved access token.
        
        ```bash
        export KMS_TOKEN=$(hanzo-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 `KMS_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.

        <Info>
        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](./commands/token) if needed.
        </Info>
      </Step>
      <Step title="Export environment variables back into a file">
        Finally, export the environment variables from KMS to a file of choice.

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

        # export variables to a YAML file
        hanzo-kms export --format=yaml > secrets.yaml
        ```
      </Step>
    </Steps>

  </Tab>
</Tabs>

<Note>
  Starting with CLI version v0.4.0, you can now choose to log in via KMS Cloud (US/EU) or your own self-hosted instance by simply running `hanzo-kms login` and following the on-screen instructions — no need to manually set the `KMS_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 `KMS_API_URL` environment variable to `https://eu.kms.hanzo.ai` or your custom URL.

</Note>

<Warning>
  ## 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://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 `KMS_API_URL` environment variable
- Use the `--domain` flag on every command

<Tabs>
  <Tab title='Use Environment Variable (Recommended)'>
    The easiest way to ensure all CLI commands use the correct domain is to set
    the `KMS_API_URL` environment variable. This applies the domain
    setting globally to all commands:

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

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

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

    ```bash
    # Login with the domain
    hanzo-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
    hanzo-kms secrets --projectId <id> --env dev
    ```

  </Tab>
  <Tab title='Use --domain Flag'>
    The `--domain` flag can be used to set the domain for a single command. This
    applies the domain setting to the command only:

    ```bash
    # Login with domain
    hanzo-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
    hanzo-kms secrets --domain="https://your-domain.kms.hanzo.ai" --projectId=<id> --env=dev
    ```

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

  </Tab>
</Tabs>

</Warning>

<Tip>
  ## 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 `KMS_CUSTOM_HEADERS` environment variable:

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

# Execute KMS commands after setting the environment variable
hanzo-kms secrets
```

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

</Tip>

## History

Your terminal keeps a history with the commands you run. When you create KMS secrets directly from your terminal, they'll stay there for a while.

For security and privacy concerns, we recommend you to configure your terminal to ignore those specific KMS commands.

<Accordion title="Ignore commands">
  <Tabs>
    <Tab title="Unix/Linux">
        <Tip>
          `$HOME/.profile` is pretty common but, you could place it under `$HOME/.profile.d/kms.sh` or any profile file run at login 
        </Tip>

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

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

    </Tab>
    <Tab title="Windows">
        If you're on WSL, then you can use the Unix/Linux method.

        <Tip>
          Here's some [documentation](https://superuser.com/a/1658331) about how to clear the terminal history, in PowerShell and CMD
        </Tip>

    </Tab>

  </Tabs>
</Accordion>

## FAQ

<AccordionGroup>
  <Accordion title="Can I connect the CLI to my self-hosted or non-US Cloud KMS instance?">
    Yes. The CLI is set to connect to 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 KMS US Cloud, EU Cloud, or your own self-hosted instance. Simply execute the `hanzo-kms login` command and follow the on-screen instructions.

     #### Method 2: Export environment variable

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

    <Tabs>
    <Tab title="Linux/MacOs">
      ```bash
      # Set the API URL
      export KMS_API_URL="https://your-self-hosted-kms.hanzo.ai"

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

      # Remove the setting
      unset KMS_API_URL
      ```

    </Tab>
    <Tab title="Windows Powershell">
      ```bash
      # Set the API URL
      setx KMS_API_URL "https://your-self-hosted-kms.hanzo.ai"

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

      # Remove the setting
      setx KMS_API_URL ""

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

    </Tab>

  </Tabs>

    #### 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:

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

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

    <Tip>
      **Best Practice:** Use `KMS_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.
    </Tip>

  </Accordion>
  <Accordion title="Can I use the CLI with service tokens?">
    To use KMS for non local development scenarios, please create a service token. The service token will allow you to authenticate and interact with KMS. Once you have created a service token with the required permissions, you’ll need to feed the token to the CLI.

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

    #### Pass via shell environment variable
    The CLI is configured to look for an environment variable named `KMS_TOKEN`. If set, it’ll attempt to use it for authentication.

    ```bash
      export KMS_TOKEN=<service-token>
    ```

  </Accordion>
</AccordionGroup>