CLI References

humctl is the command line interface for Humanitec

Quick Start

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
apply n/a Creates or updates an object based on a Humanitec Manifest.
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 deploys, envs, sets Returns a delta of the differnce between 2 deployment sets.
get all kinds Fetches the requested object.
help n/a Get help on a command. (e.g. humctl help deploy)
update deltas Makes a change to an object.
version n/a Get the current version of the tool.
api n/a Make raw authenticated API requests to the Humanitec API.

Run humctl help COMMAND for details of a specific command.

Output

All output is JSON or nothing. Errors are written to stderr and fatal errors will result in a non-zero exit code.

The expected usage is that the output is piped into jq for further manipulation.

Configuration

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_CONTEXT The context in which to run commands.
HUMANITEC_TOKEN A Humanitec static or session token.
API_PREFIX Defaults to https://api.humanitec.io

Config File

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

Property type Description
apiPrefix string The Humanitec API to use. (Defaults to https://api.humanitec.io)
context string The context in which to run commands.
outputFormat string One of yaml or json. (Defaults to yaml)
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:

/orgs/my-org/apps/my-app/envs/my-env

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 /orgs/my-org/apps/my-app/envs/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 apps/my-other-app/envs/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 envs/second-env/deploys/+2 /orgs/my-org/apps/my-app/envs/second-env/deploys/eaaa4a64e8b51df0
deploys /orgs/my-org/apps/my-other-app/envs/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:

apiVersion: core.api.humanitec.io/v1
kind: Environment
metadata:
  id: dev-2
object:
  name: Secondary Dev
  type: development

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

Examples

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 deploys +0 +1

Compare the current environment to the production environment:

humctl diff envs . production

Limitations

  • Only YAML and JSON are supported as output format.
  • Login not yet supported. It is suggested that you set the HUMANITEC_TOKEN environment variables with the appropriate token.

API References

Constraints