Command-Line Interface

Humio can be controlled via a command-line interface (CLI), called humioctl; short for “Humio Control”.

The command takes sub-commands such as search and cluster to inspect and administer cluster properties or search and send data to Humio.

To view a list of the available commands at any time, use humioctl help to get a summary of the available commands:

shell
humioctl help

Common Management Commands:
users <subcommand>
parsers <subcommand>
views <subcommand>
status

Usage:
humioctl [subcommand] [flags] [arguments]
humioctl [command]

Available Commands:
alerts        Manage alerts
cluster       Manage cluster
completion    Generate auto-completions script for the specified shell (bash or zsh)
health        Health
help          Help about any command
ingest        Send data to Humio.
ingest-tokens Manage ingest tokens
license       Manage the Humio license [Root Only]
actions       Manage actions
packages      [BETA] Manage packages
parsers       Manage parsers
profiles      List and manage configuration profiles.
repos         Manage repositories
search        Search
status        Shows general status information
users         Manage users [Root Only]
views         Manage views

Flags:
  -a, --address string               The HTTP address of the Humio cluster. Overrides the value in your
                                     config file.
   --ca-certificate-file string      File path to a file containing the CA certificate in PEM format.
                                     Overrides the value in your config file.
  -c, --config string                Config file (default is $HOME/.humio/config.yaml)
  -h, --help                         help for humioctl
   --insecure                        By default, all encrypted connections will verify that the hostname
                                     in the TLS certificate matches the name from the URL. Set this to
                                     true to ignore hostname validation.
  -u, --profile string               Name of the config profile to use
  -t, --token string                 The API token to user when talking to Humio. Overrides the value
                                     in your config file.
   --token-file string               File path to a file containing the API token. Overrides the value
                                     in your config file and the value of --token.
  -v, --version                      Print the client version

Use "humioctl [command] --help" for more information about a command.

humioctl returns a non-zero status code in the event of an error.

To stream the content of /var/log/system.log data to Humio:

shell
tail -f /var/log/system.log | humioctl ingest -o

It is important to note that while humioctl has some support for sending data to Humio, it should not be used as the primary way to ship logs to Humio. You should use a datashipper like for example, Vector or Filebeat. See Ingesting Data for a list of available ingest tools.

Installation

Simply download the CLI using one of the options below, and run humioctl. The application will guide you in setting up your environment.

  • MacOS

shell
brew tap humio/humio
brew install humioctl
  • Linux (via Snapcraft)

shell
snap install humioctl
  • Nix

shell
nix-env -i humioctl
  • Any OS (via Go)

shell
go get github.com/humio/cli/cmd/humioctl

Initializing humioctl

The first time humioctl is executed, it will need to be configured to connected to a default Humio instance.

To perform the intitalization, execute humioctl without any arguments and this will start the configuration process:

shell
 humioctl
  , ,
 (O,o)
 |)__)
 -"-"-

Welcome to Humio

This will guide you through setting up the Humio CLI.

Which Humio instance should we talk to?

If you are not using Humio Cloud enter the address of your Humio installation,
e.g. http://localhost:8080/ or https://humio.example.com/

Address (default: https://cloud.humio.com/ [Hit Enter]):

You will need to enter the URL of the default instance. The connection will be tested to ensure that it works. If the connection could not be verified you will be prompted again for the URL.

shell

==> Testing Connection…

==> Testing Connection…

==> Testing Connection… [Ok]

If you are connecting to the US or EU cloud, or secured installation, you must enter your API token as displayd on your API token within your Account settings page. You can optionally open a web browser to the correct page.

python
Paste in your Personal API Token

To use Humio's CLI you will need to get a copy of your API Token.
The API token can be found on the 'Account Settings' page of the UI.
If you are running Humio without authorization just leave the API Token field empty.

Would you like us to open a browser on the account page? [Y/n]: n

API Token: ***********************

Once the API token has been added, the configuration will be saved:

shell
==> Logged in as: developer

==> Writing settings to: /home/mc/snap/humioctl/12/.humio/config.yaml

The authentication info has been saved to the profile 'default'.
If you work with multiple user accounts or Humio servers you can
add more profiles using `humio profiles add <name>`.

Bye bye now!

You can confirm correct operation by using the humioctl status command:

shell
humioctl status
Status : OK
Address : http://localhost:8080/
Version : 1.31.0--build-32501--sha-a7699507657391712a8a0c2a22e2184f22a04a85
Username : developer

Open Source

The CLI is open source and freely available from Github. Contributions and suggestions are very welcome.

Humio CLI Github Repository