Sensu CLI (sensuctl)

Sensu 2.0 can be configured and used with the sensuctl (pronounced “sensu cuddle”) command line utility.

Installation

macOS

Download the latest release.

curl -LO https://storage.googleapis.com/sensu-binaries/$(curl -s https://storage.googleapis.com/sensu-binaries/latest.txt)/darwin/amd64/sensuctl

Optionally, if you would like to download a specific release, replace {VERSION} in the command below.

curl -LO https://storage.googleapis.com/sensu-binaries/{VERSION}/darwin/amd64/sensuctl

Make the sensuctl binary executable.

chmod +x sensuctl

Move the executable into your PATH.

sudo mv sensuctl /usr/local/bin/

Debian / Ubuntu

Add the Sensu nightly repository (this step can be skipped if you previously added the repository on the backend/agent installation page).

curl -s https://packagecloud.io/install/repositories/sensu/nightly/script.deb.sh | sudo bash

Install the Sensu CLI package.

sudo apt-get install sensu-cli

RHEL / CentOS

Add the Sensu nightly repository (this step can be skipped if you previously added the repository on the backend/agent installation page).

curl -s https://packagecloud.io/install/repositories/sensu/nightly/script.rpm.sh | sudo bash

Install the Sensu CLI package.

sudo yum install sensu-cli

Configure

Sensuctl must be configured before it can connect to your Sensu cluster. Run the configure command to get started.

$ sensuctl configure
? Sensu Backend URL: http://127.0.0.1:8080
? Username: admin
? Password: *********
? Organization: default
? Environment: default
? Preferred output format: tabular

Default User

By default, your Sensu installation comes with a single user named admin. This user has the password P@ssw0rd! and it is strongly recommended that you change it immediately. To do so, you’ll first want to authenticate using the sensuctl tool.

sensuctl configure

? Sensu Base URL: http://my-sensu-host:8080
? Username: admin
? Password:  *********
? ...

Once authenticated, you can use the change-password command.

$ sensuctl user change-password --interactive
? Current Password:  *********
? Password:          *********
? Confirm:           *********

Tweak Values

You can change individual values with the config sub-command.

sensuctl config set-organization default
sensuctl config set-environment prod

Getting Help

All Sensu sub-commands have a --help flag that returns more information on using the command and if applicable any sub-commands it has.

$ sensuctl --help
sensuctl controls Sensu instances

Usage:	sensuctl COMMAND

Flags:
      --api-url string        host URL of Sensu installation
      --cache-dir string      path to directory containing cache & temporary files (default "/home/eric/.cache/sensu/sensuctl")
      --config-dir string     path to directory containing configuration files (default "/home/eric/.config/sensu/sensuctl")
      --environment string    environment in which we perform actions (default "default")
  -h, --help                  help for sensuctl
      --organization string   organization in which we perform actions (default "default")

Commands:
  completion   Output shell completion code for the specified shell (bash or zsh)
  configure    Initialize sensuctl configuration
  create       create new resources from file or STDIN
  logout       Logout from sensuctl
  version      Show the sensu-ctl version information

Management Commands:
  asset        Manage assets
  check        Manage checks
  config       Modify sensuctl configuration
  entity       Manage entities
  environment  Manage environments
  event        Manage events
  extension    Manage extension registry
  filter       Manage filters
  handler      Manage handlers
  hook         Manage hooks
  mutator      Manage mutators
  organization Manage organizations
  role         Manage roles
  silenced     Manage silenced subscriptions and checks
  user         Manage users

Run 'sensuctl COMMAND --help' for more information on a command.

Create

The sensuctl create command allows you to create and/or update resources by reading from STDIN or a flag configured file (-f). The accepted format of the create command is wrapped-json, which wraps the contents of the resource in spec and identifies its 2.x type (see below for an example, and this table for a list of supported types).

{
  "type": "CheckConfig",
  "spec": {
    "name": "marketing-site",
    "command": "check-http.rb -u https://dean-learner.book",
    "subscriptions": ["demo"],
    "interval": 15,
    "handlers": ["slack"],
    "organization": "default",
    "environment": "default"
   }
}
{
  "type": "Handler",
  "spec": {
    "name": "slack",
    "type": "pipe",
    "command": "handler-slack --webhook-url https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX --channel monitoring'",
    "environment": "default",
    "organization": "default"
  }
}

Write all checks to my-resources.json in wrapped-json format:

sensuctl check list --format wrapped-json > my-resources.json

Create all resources in wrapped-json format from my-resources.json:

cat my-resources.json | sensuctl create

Supported types

wrapped-json types
AdhocRequest adhoc_request Asset asset
Check check CheckConfig check_config
Entity entity Environment environment
Event event EventFilter event_filter
Extension extension Handler handler
Hook hook HookConfig hook_config
Mutator mutator Organization organization
Role role Silenced silenced

Shell Auto-Completion

Installation (Bash Shell)

Make sure bash completion is installed. If you use a current Linux in a non-minimal installation, bash completion should be available. On a Mac, install with:

brew install bash-completion

Then add the following to your ~/.bash_profile:

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

When bash-completion is available we can add the following to your ~/.bash_profile:

source <(sensuctl completion bash)

You can now source your ~/.bash_profile or launch a new terminal to utilize completion.

source ~/.bash_profile

Installation (ZSH)

Add the following to your ~/.zshrc:

source <(sensuctl completion zsh)

You can now source your ~/.zshrc or launch a new terminal to utilize completion.

source ~/.zshrc

Usage

sensuctl:

> $ sensuctl <kbd>Tab</kbd>
check       configure   event       user
asset       completion  entity      handler

sensuctl:

> $ sensuctl check <kbd>Tab</kbd>
create  delete  import  list

For more details on sensuctl commands, check out the reference guide.