CLI

hctl is the CLI for the Humanitec Platform Orchestrator.

Current CLI version: 1.38.2

Installation #

Install hctl on Linux #

1. Download the latest release with the command

   • x64-86
   • ARM64

   curl -fLO https://github.com/humanitec/hctl/releases/download/v1.38.2/hctl_1.38.2_linux_amd64.tar.gz
   tar xvzf hctl_1.38.2_linux_amd64.tar.gz
   rm hctl_1.38.2_linux_amd64.tar.gz README.md
   

   curl -fLO https://github.com/humanitec/hctl/releases/download/v1.38.2/hctl_1.38.2_linux_arm64.tar.gz
   tar xvzf hctl_1.38.2_linux_arm64.tar.gz
   rm hctl_1.38.2_linux_arm64.tar.gz README.md
   

2. Install hctl

   sudo install -o root -g root -m 0755 hctl /usr/local/bin/hctl
   

   

   Note

   If you do not have root access on the target system, you can still install hctl to the ~/.local/bin directory:

   chmod +x hctl
   mkdir -p ~/.local/bin
   mv ./hctl ~/.local/bin/hctl
   # and then append (or prepend) ~/.local/bin to $PATH
   

Install hctl on macOS #

Homebrew #

If you are on macOS and using the Homebrew  package manager, you can install hctl with Homebrew.

1. Run the installation command:

   brew install humanitec/tap/hctl
   

Manually #

1. Download the latest release with the command

   • Intel
   • Apple Silicon

   curl -fLO https://github.com/humanitec/hctl/releases/download/v1.38.2/hctl_1.38.2_darwin_amd64.tar.gz
   tar xvzf hctl_1.38.2_darwin_amd64.tar.gz
   rm hctl_1.38.2_darwin_amd64.tar.gz README.md
   

   curl -fLO https://github.com/humanitec/hctl/releases/download/v1.38.2/hctl_1.38.2_darwin_arm64.tar.gz
   tar xvzf hctl_1.38.2_darwin_arm64.tar.gz
   rm hctl_1.38.2_darwin_arm64.tar.gz README.md
   

2. Install hctl

   chmod +x ./hctl
   sudo mv ./hctl /usr/local/bin/hctl
   sudo chown root: /usr/local/bin/hctl
   

Install hctl on Windows #

Scoop #

If you are on Windows and using the Scoop  package manager, you can install hctl with Scoop.

1. Run the installation command:

   scoop bucket add humanitec https://github.com/humanitec/scoop-bucket
   scoop install humanitec/hctl
   

Manually #

1. Download the latest release .

2. Decompress the zip file, and move the binary to your PATH.

Available as Docker Image #

hctl is also published as Docker Image , which can be used like docker run --rm -it ghcr.io/humanitec/hctl:1.38.2.

Install hctl in GitHub Actions #

A GitHub action is available in the GitHub Marketplace  to install the hctl binary and add it to the $PATH.

jobs:
  example:
    runs-on: ubuntu-latest
    env:
      HUMANITEC_ORG: ${{ vars.HUMANITEC_ORG }}
      HUMANITEC_AUTH_TOKEN: ${{ secrets.HUMANITEC_AUTH_TOKEN }}
    steps:
    - name: Setup hctl
      uses: humanitec/setup-hctl@v1
      with:
        version: "1"
        token: ${{ secrets.GITHUB_TOKEN }}
    - name: Deploy a manifest
      run: hctl deploy my-project my-environment ./manifest.yaml

The version field can be an exact version such as “1.36.7” or a range such as “1”, “1.36”, “^1.36.0”.

Validate your installation #

Run hctl --version to ensure hctl is in your path. Expected output, matching your installed version: hctl version github.com/humanitec/hctl <version XX.YY.ZZ> <commit-hash> <commit-date>

CLI cheat sheet #

An overview of common and useful CLI commands is available in the CLI cheat sheet.

Configuration #

hctl will maintain a local configuration in a config file located at ~/.config/hctl/config.yaml. Use the command hctl config or the list below to see available configuration items.

Each configuration item can be overridden using an Environment Variable.

The command hctl config show displays the effective configuration, taking any override into account.

Commands #

hctl follows a hierarchical command structure generally adhering to this pattern:

hctl <verb> <object> [additional classification]

E.g. to see the details of a particular Provider, use this command:

hctl get provider <type> <id>

All available commands are listed and explained in the CLI online help. Use the -h or --help flag to see usage details on any command level, e.g.:

hctl get provider -h