CLI References

humctl is the command line interface for Humanitec

Quick Start


Visit CLI for instructions how to install the humctl.

Basic usage

humctl follows a standard command structure. The basic usage is:

humctl COMMAND TYPE [arguments...]

Different commands accept different types. Types are types of Humanitec objects such as defined in the API such as apps, envs or sets. Arguments are usually IDs, values or switches. Switches are available in a long form (e.g. --message) or short form (e.g. -m.) Short form switches cannot be combined into a single switch.

The commands supported by the CLI so far include:

Command Types Description
api n/a Make raw authenticated API requests to the Humanitec API.
apply n/a Creates or updates an object based on a Humanitec Manifest.
completion n/a Generate the autocompletion script for the specified shell.
config n/a Show the value of a particular config key.
create apps, deltas, envs Creates a new object.
delete all kinds Deletes an object.
deploy deltas, deploys, sets Starts a new deployment to an environment.
diff sets Returns a delta of the difference between 2 deployment sets.
get all kinds Fetches the requested object.
help n/a Get help on a command. (e.g. humctl help deploy)
login n/a Login to the CLI with the help of a web browser.
resources n/a Commands to manage your resources.
score n/a Commands to operate on Score files.
update deltas Makes a change to an object.
version n/a Get the current version of the tool.

Run humctl help COMMAND for details of a specific command.


⚠️ The default text output is subject to change. if you need to access CLI output programmatically, please consider using –output to specify another output format.

Errors are written to stderr and fatal errors will result in a non-zero exit code.


humctl will read from a config file located by default at .humctl in the users home directory. These configurations can be overridden using Environment Variables.

Environment Variables

humctl understands the following optional environment variables:

Environment Variable Description
HUMANITEC_TOKEN A Humanitec static or session token.
HUMANITEC_ORG The Organization in which to run commands.
HUMANITEC_APP The Application in which to run commands.
HUMANITEC_ENV The Environment in which to run commands.
HUMANITEC_API_PREFIX The Humanitec API to use. (Defaults to
HUMANITEC_OUTPUT One of yaml, json or text. (Defaults to text)
HUMANITEC_CONFIG Path to the config file described below. (Defaults to ~/.humctl)

Config File

The humctl config file is a YAML file with the following properties:

Property type Description
api_prefix string The Humanitec API to use. (Defaults to
org string The Organization in which to run commands.
app string The Application in which to run commands.
env string The Environment in which to run commands.
output string One of yaml, json or text. (Defaults to text)
token string A Humanitec static or session token

All properties are optional.

IDs, Context and Expansions

Objects in Humanitec exist in a hiearchy. For example, an Environment always belongs to a single Application and an Application always belongs to a single Organization. The fully qualified ID for an object in Humanitec is equivelant to its path in the Humanitec API. For example, the fully qualified ID for an environment called my-env in an application called my-app in organization my-org is:


Expansions using Current Context

As most users spend their time working with just one or two environments in a single Application, humctl allows users to define a context which can be used to figure out the full ID from just a fragment. For example, if the context was --org my-org --app my-app --env my-env, then the following expansions could happen:

Type Short ID Fully Qualified ID
apps my-other-app /orgs/my-org/apps/my-other-app
envs second-env /orgs/my-org/apps/my-app/envs/second-env
envs --app my-other-app --env other-apps-env /orgs/my-org/apps/my-other-app/envs/other-apps-env

This also works for other objects that are scoped within an Application or Enviornment:

Type Short ID Fully Qualified ID
sets dRZxTxhPImjJ2JIWXj-ZGiu_4-ov5UfWxK-eUNt6zvh /orgs/my-org/apps/my-app/sets/dRZxTxhPImjJ2JIWXj-ZGiu_4-ov5UfWxK-eUNt6zvh
deltas 18e8fd691c3be9c023f5dc41d0cb2181d524fd01 /orgs/my-org/apps/my-app/deltas/18e8fd691c3be9c023f5dc41d0cb2181d524fd01

Current Context and Active objects

As a further shortcut, the current context value can be used directly by using . in place of the ID alltogether:

Type Short ID Fully Qualified ID
apps . /orgs/my-org/apps/my-app
envs . /orgs/my-org/apps/my-app/envs/my-env

This also works with other objects that can have be active. The last delta created will be remembered by humctl and will be inserted if you use . in place of a delta. The last Deployment in an Environment counts as the “active” Deployment, so if you use . in place of a deployment, you will get the active deployment of the current Environment in the context.

For example, assuming the most recently created deltas has ID 18e8fd691c3be9c023f5dc41d0cb2181d524fd01 and the last deployment an ID of 166a15b85e58dcee:

Type Short ID Fully Qualified ID
deltas . /orgs/my-org/apps/my-app/deltas/18e8fd691c3be9c023f5dc41d0cb2181d524fd01
deploys . /orgs/my-org/apps/my-app/envs/my-env/deploys/166a15b85e58dcee

Sequential objects

A final shortcut applies to objects that have order. This currently only applies to Deployments. Deployments in an Environment have an order as they occur on after eachother in an environment. The sequential shortcut is a + followed by the offset down the list and is used in place of an ID. In this case +0 would get the current item and +2 would get the item next-but-one in the list. For example:

Type Short ID Fully Qualified ID
deploys . /orgs/my-org/apps/my-app/envs/my-env/deploys/166a15b85e58dcee
deploys +0 /orgs/my-org/apps/my-app/envs/my-env/deploys/166a15b85e58dcee
deploys +2 /orgs/my-org/apps/my-app/envs/my-env/deploys/964f2eae8b51a661

The sequential shortcut can also be used in combination with a partial or fully qualified ID:

Type Short ID Fully Qualified ID
deploys --env second-env deploys/+2 /orgs/my-org/apps/my-app/envs/second-env/deploys/eaaa4a64e8b51df0
deploys --org my-org --app my-other-app --env different-env deploys/+1 /orgs/my-org/apps/my-other-app/envs/different-env/deploys/411f9bbe01e4dc62

Humanitec Manifests

Humanitec uses a similar YAML structure to Kubernetes when defining its YAML files. The structure has the following basic format:

kind: Environment
  id: dev-2
entity: # modifiable properties
  name: Secondary Dev
  type: development
status: # read-only properties
  created_at: "2020-06-12T07:49:12.720677Z"

The manifests can be used with the apply command to provide an “as code” approach to using Humanitec.

Score integration

With humctl score, you can easily operate on your Score files. Currently, the score command supports the following subcommands:

Command Description
available-resource-types List available Resource Types.
init Initialize the example Score file.
validate Validate the specified Score file.


Create a delta to add an environment variable to the main container in the sample-app workload:

humctl create delta --name "add variable"
humctl update delta . add modules/sample-app/spec/containers/main/variables/NEW_VAR '"Hello World!"'

Deploy the current delta to the current environment:

humctl deploy delta . . --comment "Adding NEW_VAR to sample-app"

Comparing what is currently deployed with what was deployed before:

humctl diff sets deploy/+0 deploy/+1

Compare the current environment to the production environment:

humctl diff sets env/. env/production