Command-Line Interface (humioctl)

LogScale 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 LogScale.

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

  Sending Data:

    LogScale's CLI is not a replacement for fully-featured data-shippers like
    LogStash, FileBeat or MetricBeat. It can be handy to easily send logs
    to LogScale, e.g examine a local log file or test a parser on test input.

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

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

  or

    $ humioctl ingest -o --tail=/var/log/system.log

  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 autocompletions script for the specified shell (bash or zsh)
    files         Manage files
    groups        Manage groups
    health        Health
    help          Help about any command
    ingest        Send data to LogScale.
    ingest-tokens Manage ingest tokens
    license       Manage the LogScale license [Root Only]
    notifiers     Manage notifiers
    packages      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 LogScale 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
        --proxy-organization string    Commands are executed in the specified organization.
    -t, --token string                 The API token to use when talking to LogScale. 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 LogScale:

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 LogScale, it should not be used as the primary way to ship logs to LogScale. 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 install github.com/humio/cli/cmd/humioctl@latest

Initializing humioctl

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

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

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

  Welcome to LogScale

  This will guide you through setting up the LogScale CLI.

  Which LogScale instance should we talk to?

  If you are not using LogScale Cloud enter the address of your LogScale 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 displayed on your API token within your Account settings page. You can optionally open a web browser to the correct page.

default
Paste in your Personal API Token

  To use LogScale'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 LogScale 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 LogScale 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.

LogScale CLI Github Repository