CLI References

humctl is the command line interface for Humanitec

Quick Start #

Installation #

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:

Run humctl help COMMAND for details of a specific command.

Output #

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.

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:

Config File #

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

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 --org my-org --app my-app --env my-env, then the following expansions could happen:

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

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:

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:

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:

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

Humanitec Manifests #

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

apiVersion: entity.humanitec.io/v1b1
kind: Environment
metadata:
  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, you can easily operate and deploy your Score files. Currently, the score command supports the following subcommands:

Listing available Resource Types #

Depending on your organization, developers might have access to different Resource Types. The humctl tool provides an easy way for developers to discover what is available to them. Use the following commands:

• List all available resource types: humanitec score available-resource-types
• Filter the list by a specific Resource Type: humctl score available-resource-types --filter-type TYPE
• Ensure you are using the correct Resource Types in your Score files: humctl score validate

The latter validation step can prevent errors and streamline the provisioning process by checking your Score file for any incorrect Resource Types and providing feedback on necessary corrections.

For the best developer experience, use the VSCode Extension that displays Resource Types and validates your Score file in real-time. This extension integrates seamlessly with your development workflow, providing instant feedback and helping you adhere to best practices.

Deploying Score files #

To deploy a single workload, you can simply use humctl score deploy. It will use the score.yaml file from the directory where the binary was executed. To modify that path, you can use the --file flag. Additionally, you can specify extension files using the --extensions flag and overrides using the --overrides flag.

Removing Workloads #

Add the --remove flag to the humctl score deploy command to remove a Workload instead of deploying it, e.g. humctl score deploy -f scoreWithWorkloadToRemove.yaml --remove.

Configuration #

To avoid passing extension and override files each time and to deploy multiple workloads at once, you can define a deploy configuration and specify it via the --deploy-config flag. This configuration describes where the Score files are located and matches them with their respective extensions and overrides. An example file looks like this:

deploy-config.yaml ( view on GitHub ) :

apiVersion: config.humanitec.io/v1b1
kind: ScoreDeployConfig
workloads:
  - name: example-service
    specFile: ./score.example-service.yaml
    extensionsFile: ./score.humanitec.yaml
  - name: another-service
    specFile: ./score.another-service.yaml
    extensionsFile: ./score.humanitec.yaml

Available attributes in your deploy configuration are:

There is no specific order of deployment for the workloads. All the specified changes from the Score files are combined into a single delta and pushed as one deployment.

If an error occurs during the deployment of the combined delta, the entire deployment process fails. The error messages can be found in the pipeline run logs.

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 sets deploy/+0 deploy/+1

Compare the current environment to the production environment:

humctl diff sets env/. env/production