CLI cheat sheet

This page contains a list of commonly used hctl CLI commands and flags.

Installation #

Visit the CLI page for instructions on installing the hctl CLI.

Prequisites #

All CLI commands shown in this page require the environment variables HUMANITEC_ORG and HUMANITEC_API_URL to be set. See CLI configuration for details.

export HUMANITEC_ORG=my-org                                         # Set id of the Organization in which to run commands
export HUMANITEC_API_URL=https://platform-orchestrator.example.com  # Set the base URL of the Orchestrator API

Configuration #

CLI base configuration #

hctl config set-org    # Set the id of the default Organization in which to run commands in the local config
hctl config set-url    # Set the base URL of the Orchestrator API in the local config

hctl config show       # Show the effective configuration, taking env var overrides into account

Project structure #

hctl create project my-project             # Create a project named "my-project"
hctl list projects                         # List all projects
hctl create environment-type development   # Create an environment type named "development"

# Create an environment named "dev" in the project "my-project" with environment type "development"
hctl create environment my-project dev --set=env_type_id=development

Providers #

# Create a provider named "default" of type "kubernetes" with a version contraint and blank configuration
hctl create provider kubernetes default --set source=hashicorp/kubernetes \
  --set version_constraint='~> 2.36' \
  --set-json '{"configuration": {}}'

hctl list providers                    # List all providers
hctl list providers --type kubernetes  # List all providers of type "kubernetes"
hctl get provider kubernetes default   # Get the provider of type "kubernetes" named "default"

Runners #

# Create a runner named "default" of type "kubernetes" reading data from a local kubeconfig
# running jobs in the "default" namespace using the "humanitec-runner" service account
# and using "kubernetes" state storage
hctl create runner default \
  --set=runner_type=kubernetes \
  --set=runner_configuration='{"cluster":{"cluster_data":{"certificate-authority-data": "'"$(kubectl config view -o jsonpath='{.clusters[?(@.name == "my-cluster")].cluster.certificate-authority-data}' --raw)"'","server":"https://kubernetes.default.svc.cluster.local"},"auth":'"$(kubectl config view -o jsonpath='{.users[?(@.name == "my-user")].user}' --raw)"'}, "job":{"namespace":"default","service_account":"humanitec-runner"}}' \
  --set=state_storage_type=kubernetes \
  --set=state_storage_configuration='{"namespace":"default","secret_suffix":""}'

hctl list runners        # List all runners
hctl get runner default  # Get the runner named "default"

# Create a runner rule for runner "my-runner", project "my-project" and environment type "development"
hctl create runner-rule --set=runner_id=my-runner \
  --set=project_id=my-project \
  --set=env_type_id=development
hctl create runner-rule --set=runner_id=my-runner # Create an empty runner rule ("always match")

Resource types #

# List available resource types in the "development" environment of project "my-project"
hctl list available-resource-types my-project development

# Create a resource type named "s3" with a non-empty output schema
hctl create resource-type s3 \
  --set=name=S3 \
  --set=output_schema='{"type":"object","properties":{"arn":{"type":"string"},"bucket":{"type":"string"},"region":{"type": "string"},"endpoint":{"type": "string"}}}'

Modules #

hctl list modules          # List all modules
hctl get module my-module  # Get the module named "my-module"

# Create a module named "my-module" with a resource type of "example-type"
# referencing a module in an external git repository,
# mapping the module provider "kubernetes" to the Orchestrator provider "kubernetes.default",
# and providing a value for the module input variable "my-variable"
hctl create module my-module \
    --set=resource_type=example-type \
    --set=module_source=git::https://git.example.com/my-project/my-repo \
    --set=provider_mapping='{"kubernetes": "kubernetes.default"}' \
    --set=module_inputs='{"my-variable": "my-value"}'

# Create a blank module rule ("match anything") on the module "my-module"
hctl create rule --set=module_id=my-module

Deployments #

Performing deployments #

# Deploy a local manifest file into the "development" environment of project "my-project"
hctl deploy my-project development ./my-app-manifest.yaml
# Deploy a local manifest file and show the deployment outputs
hctl deploy my-project development ./my-app-manifest.yaml --output -

# Deploy a local Score file into the "development" environment of project "my-project"
hctl score deploy my-project development ./score.yaml

hctl deploy my-project development my-app-manifest.yaml --dry-run   # Validate the request but do not execute the deployment
hctl deploy my-project development my-app-manifest.yaml --plan-only # Set deployment mode to plan only
hctl deploy my-project development --destroy                        # Set deployment mode to destroy

# Promote the last stateful deployment in the "staging" environment into the "production" environment in the same project
hctl deploy my-project production environment://staging
# Deploy the last stateful deployment for the "development" environment, this acts like a redeployment
hctl deploy my-project development deployment://HEAD
# Cross-deploy a deployment id in the same org to the "development" environment
hctl deploy my-project development deployment://01234567-89ab-cdef-0123-456789abcdef

Observing deployments #

hctl list deployments                                    # List all deployments
hctl list deployments my-project                         # Get the deployments in project "my-project"
hctl get deployment 12345678-abcd-dcba-1234-ba0987654321 # Get the deployment with id 12345678-abcd-dcba-1234-ba0987654321

Active resources #

hctl list active-resource-nodes my-project development  # Get all active resources nodes in the "development" environment of project "my-project"