Sensuctl CLI

Sensuctl is a command line tool for managing resources within Sensu. It works by calling Sensu’s underlying API to create, read, update, and delete resources, events, and entities.

Sensuctl is available for Linux, macOS, and Windows. For Windows operating systems, sensuctl uses cmd.exe for the execution environment. For all other operating systems, sensuctl uses the Bourne shell (sh).

Read Install Sensu to install and configure sensuctl.

First-time setup and authentication

To set up sensuctl, run sensuctl configure to log in to sensuctl and connect to the Sensu backend:

sensuctl configure

The sensuctl configure command starts the prompts for interactive setup. The first prompt is for the authentication method you wish to use: username/password or OIDC.

Sensuctl uses your username and password or OIDC credentials to obtain access and refresh tokens via the Sensu /auth API. The access and refresh tokens are HMAC-SHA256 JSON Web Tokens (JWTs) that Sensu issues to record the details of users’ authenticated Sensu sessions. The backend digitally signs these tokens, and the tokens can’t be changed without invalidating the signature.

Upon successful authentication, sensuctl stores the access and refresh tokens in a “cluster” configuration file under the current user’s home directory. For example, on Unix systems, sensuctl stores the tokens in $HOME/.config/sensu/sensuctl/cluster.

Username/password authentication

The sensuctl configure interactive prompts require you to select the username/password authentication method and enter the Sensu backend URL, namespace, and preferred output format. Then you will be prompted to enter your username and password Sensu access credentials.

Username/password authentication applies to the following authentication providers:

This example shows the username/password authentication method:

Authentication method: username/password
Sensu Backend API URL: http://127.0.0.1:8080
Namespace: default
Preferred output format: tabular
Username: YOUR_USERNAME
Password: YOUR_PASSWORD

OIDC authentication

The sensuctl configure interactive prompts require you to select the OIDC authentication method and enter the Sensu backend URL, namespace, and preferred output format. Then, if you are using a desktop, a browser will open to allow you to authenticate and log in via your OIDC provider.

This example shows the OIDC authentication method:

Authentication method: OIDC
Sensu Backend API URL: http://127.0.0.1:8080
Namespace: default
Preferred output format: tabular
Launching browser to complete the login via your OIDC provider at following URL:

  http://127.0.0.1:8080/api/enterprise/authentication/v2/oidc/authorize?callback=http%3A%2F%2Flocalhost%3A8000%2Fcallback

You may also manually open this URL. Waiting for callback...

If a browser does not open, launch a browser to complete the login via your OIDC provider at the Sensu backend URL you entered in your sensuctl configuration.

NOTE: You can also use sensuctl login oidc to log in to sensuctl with OIDC.

Sensu backend URL

The Sensu backend URL is the HTTP or HTTPS URL where sensuctl can connect to the Sensu backend server. The default URL is http://127.0.0.1:8080.

To connect to a Sensu cluster, connect sensuctl to any single backend in the cluster. For information about configuring the Sensu backend URL, read the backend reference.

sensuctl configure flags

Run sensuctl configure -h to view command-specific flags you can use to set up sensuctl and bypass interactive mode. The following table lists the command-specific flags.

Flag Function and important notes
--format Preferred output format (default “tabular”). String.
-h or --help Help for the configure command.
-n or --non-interactive Do not administer interactive questionnaire.
--oidc Use an OIDC provider for authentication (instead of username and password).
--password string User password. String.
--port Port for local HTTP webserver used for OAuth 2 callback during OIDC authentication (default 8000). Integer.
--url The Sensu backend url (default “http://127.0.0.1:8080”). String.
--username Username. String.

Configuration files

During configuration, sensuctl creates configuration files that contain information for connecting to your Sensu Go deployment. You can find these files at $HOME/.config/sensu/sensuctl/profile and $HOME/.config/sensu/sensuctl/cluster.

Use the cat command to view the contents of these files. For example, to view your sensuctl profile configuration, run:

cat .config/sensu/sensuctl/profile

The response should be similar to this example:

{
  "format": "tabular",
  "namespace": "default",
  "username": "admin"
}

To view your sensuctl cluster configuration, run:

cat .config/sensu/sensuctl/cluster

The response should be similar to this example:

{
  "api-url": "http://localhost:8080",
  "trusted-ca-file": "",
  "insecure-skip-tls-verify": false,
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_at": 1550082282,
  "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

These configuration files are useful if you want to know which cluster you’re connecting to or which namespace or username you’re currently configured to use.

Username, password, and namespace

During the Sensu backend installation process, you create an administrator username and password and a default namespace.

NOTE: For a new installation, you can set administrator credentials with environment variables during initialization. If you are using Docker and you do not include the environment variables to set administrator credentials, the backend will initialize with the default username (admin) and password (P@ssw0rd!).

Your ability to get, list, create, update, and delete resources with sensuctl depends on the permissions assigned to your Sensu user. For more information about configuring Sensu access control, read the RBAC reference.

Change admin user’s password

After you have configured sensuctl and authenticated, you can change the admin user’s password. Run:

sensuctl user change-password --interactive

You must specify the user’s current password to use the sensuctl user change-password command.

Reset a user password

To reset a user password without specifying the current password, run:

sensuctl user reset-password USERNAME --interactive

You must have admin permissions to use the sensuctl user reset-password command.

Test a user password

To test the password for a user created with Sensu’s built-in basic authentication:

sensuctl user test-creds USERNAME --password 'password'

An empty response indicates valid credentials. A request-unauthorized response indicates invalid credentials.

NOTE: The sensuctl user test-creds command tests passwords for users created with Sensu’s built-in basic authentication. It does not test user credentials defined via an authentication provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC).

For example, if you test LDAP credentials with the sensuctl user test-creds command, the backend will log an error, even if you know the LDAP credentials are correct:

{"component":"apid.routers","error":"basic provider is disabled","level":"info","msg":"invalid username and/or password","time":"2020-02-07T20:42:14Z","user":"dev"}

Generate a password hash

To generate a password hash for a specified cleartext password, run:

sensuctl user hash-password PASSWORD

The sensuctl user hash-password command creates a bcrypt hash of the specified password. You can use this hash instead of the password when you use sensuctl to create and edit users.

Preferred output format

Sensuctl supports the following output formats:

  • tabular: Output is organized in user-friendly columns (default).
  • yaml: Output is in YAML format. Resource definitions include an outer-level spec “wrapping” for resource attributes and list the resource type and api_version.
  • wrapped-json: Output is in JSON format. Resource definitions include an outer-level spec “wrapping” for resource attributes and list the resource type and api_version.
  • json: Output is in JSON format. Resource definitions do not include an outer-level spec “wrapping” or the resource type and api_version.

After you are logged in, you can change the default output format with sensuctl config set-format or set the output format per command with the --format flag.

Output format significance

To use sensuctl create to create a resource, you must provide the resource definition in yaml or wrapped-json format. These formats include the resource type, which sensuctl needs to determine what kind of resource to create.

The Sensu API uses json output format for responses for APIs in the core group. For APIs that are not in the core group, responses are in the wrapped-json output format.

Sensu sends events to the backend in json format, without the spec attribute wrapper or type and api_version attributes.

Non-interactive mode

Run sensuctl configure non-interactively by adding the -n (--non-interactive) flag.

sensuctl configure -n --url http://127.0.0.1:8080 --username YOUR_USERNAME --password YOUR_PASSWORD --format tabular

Get help

Sensuctl supports a --help flag for each command and subcommand.

List command and global flags

sensuctl --help

List subcommands and flags

sensuctl check --help

List usage and flags

sensuctl check delete --help

Manage sensuctl

The sencutl config command lets you view the current sensuctl configuration and set the namespace and output format.

View sensuctl config

To view the active configuration for sensuctl:

sensuctl config view

The sensuctl config view response includes the Sensu backend URL, default namespace for the current user, default output format for the current user, and currently configured username:

=== Active Configuration
API URL:   http://127.0.0.1:8080
Namespace: default
Format:    tabular
Username:  admin

Set output format

Use the set-format command to change the default output format for the current user.

For example, to change the output format to tabular:

sensuctl config set-format tabular

Set namespace

Use the set-namespace command to change the default namespace for the current user. For more information about configuring Sensu access control, read the RBAC reference.

For example, to change the default namespace to development:

sensuctl config set-namespace development

Log out of sensuctl

To log out of sensuctl:

sensuctl logout

To log back in to sensuctl:

sensuctl configure

View the sensuctl version number

To display the current version of sensuctl:

sensuctl version

Global flags

Global flags modify settings specific to sensuctl, such as the Sensu backend URL and namespace. You can use global flags with most sensuctl commands.

--api-key string             API key to use for authentication
--api-url string             host URL of Sensu installation
--cache-dir string           path to directory containing cache & temporary files
--config-dir string          path to directory containing configuration files
--insecure-skip-tls-verify   skip TLS certificate verification (not recommended!)
--namespace string           namespace in which we perform actions (default "default")
--timeout duration           timeout when communicating with sensu backend (default 15s)
--trusted-ca-file string     TLS CA certificate bundle in PEM format

To permanently set these flags, edit .config/sensu/sensuctl/{cluster, profile}.

Use shell autocompletion with sensuctl

Use shell autocompletion to create and run valid sensuctl commands. After you install and configure autocompletion, you can use the tab key to view and select from available options for each part of a sensuctl command directly from the command line.

Type sensuctl and press tab to view the list of available variables:

api-key               cluster-role          configure             edit                  handler               logout                role                  user
asset                 cluster-role-binding  create                entity                help                  mutator               role-binding          version
auth                  command               delete                env                   hook                  namespace             secret                
check                 completion            describe-type         event                 license               pipeline              silenced              
cluster               config                dump                  filter                login                 prune                 tessen

Type your selected variable and press tab again to view the list of available variables to complete the command:

create  delete  info    list

Type your selected variable to complete the command and press enter to run it.

Install and configure autocompletion for sensuctl

Follow the instructions in this section to install and configure Bash or zsh autocompletion for sensuctl.

Install and configure for Bash

To install and configure Bash autocompletion for sensuctl:

  1. Install bash-completion.

    NOTE: If you use a current version of Linux in a non-minimal installation, bash-completion may already be installed.

    To install bash-completion on macOS, run: 

    brew install bash-completion

    Open ~/.bash_profile, add the following lines, and save: 

    if [ -f $(brew --prefix)/etc/bash_completion ]; then
. $(brew --prefix)/etc/bash_completion
fi

  2. Open ~/.bash_profile, add the following line, and save:

    source <(sensuctl completion bash)

  3. Run the following command to source your ~/.bash_profile file so that its resources are available:

    source ~/.bash_profile

Shell autocompletion should now be available for sensuctl.

Install and configure for zsh

To install and configure zsh autocompletion for sensuctl:

  1. Open ~/.zshrc, add the following line, and save:

    source <(sensuctl completion zsh)

  2. Run the following command to source your ~/.zshrc file so that its resources are available:

    source ~/.zshrc