Chronoctl

Chronoctl is a Chronosphere-supplied app that lets you manage your organization's Chronosphere resources from the command line.

For example, to list your team's monitor definitions:

chronoctl monitors list

Getting started

To install Chronoctl, see Install Chronoctl.

To use Chronoctl, you must provide an API token and organization name to authenticate as an account with administrative privileges, either by configuring them as environment variables or passing them with the command.

After you're ready to use Chronoctl, refer to its commands to directly control your Chronosphere environment.

Command list

Requires Chronoctl version 0.53.0 or later.

Chronoctl is based on the structure of the Chronosphere API, which helps its commands be as consistent with one another as possible. This also better reflects features as they're presented for use in the Chronosphere API itself.

Flags

Each command has several flags for customizing its output or behavior.

In addition to the authentication flags, flags that are common among commands include:

• -h, --help: Outputs help text for the given command.
• --timeout: Defines a duration in seconds for the request before it times out and fails. Defaults to 30 seconds.

Chronoctl commands that return data representations of resources have additional common flags:

• -o, --output: Defines the output format. Accepts json for JSON, jsonl for JSON Lines, or defaults to yaml for YAML.

Chronoctl commands that can change the state of a resource in Chronosphere, such as chronoctl apply or resource create and update subcommands, also have:

• -d, --dry-run: If set, Chronoctl simulates but doesn't apply the manifest or change in a dry run, and then displays the predicted result.
• --no-strict: If set, Chronoctl accepts manifests or changes that contain unknown fields.

Slugs

Chronosphere identifies each resource by a unique slug, which has a 255-character length limit and contains only letters, numbers, underscores (_), and dashes (-). Slugs are case-sensitive. By default, Chronosphere generates a random slug for each resource. Chronoctl lets you optionally specify a slug when creating resources.

Configuration commands

Configuration commands are the recommended way to interact with Chronosphere resources. Use the apply command for interacting with multiple resources, but in most cases, uses the configuration commands.

Each of these commands are specific to Chronosphere resource types, which have the same following subcommands:

• create
• delete
• list
• read
• scaffold
• update

The following syntax applies to all configuration commands:

chronoctl RESOURCE COMMAND

Replace the following variables:

• RESOURCE: The resource you want to take action on, such as dashboards, monitors, or teams.
• COMMAND: The subcommand you want to use, such as create, delete, or list.

create

Creates one resource of the given type.

The create subcommand accepts the common flags of commands that can change the Chronosphere state, and the -f (--filename) flag similar to the apply command.

To create resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

For example, to create a monitor based on a monitor definition:

chronoctl monitors create -f FILE_NAME.yaml

Replace FILE_NAME with the name of the definition file you want to use.

delete

Deletes one resource of the given type that has the specified slug.

The delete subcommand accepts the common flags of commands that can change the Chronosphere state.

To delete resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

For example, to delete a monitor:

chronoctl monitors delete SLUG

Replace SLUG with the slug of the monitor you want to delete.

list

Lists all resources of the given type.

The list subcommand also accepts these flags:

• --create-file-per-object: Generates a file for each resource, with the optional --output-dir flag to specify where to write the files.
• --limit: Defines the limit of many resources to return.
• --names, --slugs: Returns results by their resource name or slug, respectively.
• --page-token: Begins listing resources from the start of a given pagination token.

Additionally, for grafana-dashboards, mapping-rules, monitors, notification-policies, recording-rules, and rollup-rules:

• --bucket-slugs: Lists rules associated with the given bucket.

For example, to list a specific monitor:

chronoctl monitors delete SLUG

Replace SLUG with the slug of the monitor you want to view.

read

Outputs one resource of the given type that has the specified slug.

The read subcommand accepts the common flags of commands that only read the Chronosphere state.

For example, to read a specific monitor:

chronoctl monitors delete SLUG

Replace SLUG with the slug of the monitor you want to read the definition for.

scaffold

Outputs an example resource definition of the given type, including inline comments documenting its properties.

For example, to output an example recording rule:

chronoctl recording-rules scaffold

update

Updates a resource of the given type.

The update subcommand accepts the common flags of commands that can change Chronosphere state, and the -f (--filename) flag similar to the apply command, and a --create-if-missing flag that creates the given resource if it doesn't already exist.

The create and update subcommands all use the common flags for commands that can change Chronosphere state.

To update resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

Core commands

Chronoctl core commands are independent of any resource type.

apply

Applies a configuration change to resources from a YAML or JSON file, or from standard input. When you apply resources with Chronoctl, Chronosphere creates them if they don't already exist.

The apply command accepts input from a file by providing the path as the value of the -f (--filename) flag.

For example, to apply a file containing a resource's YAML manifest:

chronoctl apply -f resources.yml

To apply a resource passed from standard input, use the - value of the -f flag:

chronoctl apply -f -

Upon success, the command returns the list of changes applied.

The apply command accepts the dry run (-d, --dry-run) flag, which displays the changes without applying them.

chronoctl apply -f resources.yml -d

State commands

These commands evaluate the current state of Chronosphere.

rule-evaluations list

The list subcommand is the only subcommand for rule-evaluations.

Returns a list of rule evaluation failures, including the rule's type, slug, failure count, message, and detection timestamp.

Additional commands

These commands provide additional information as you use Chronoctl.

help

Displays help text for the tool and any specified subcommand.

chronoctl help

version

Displays the version, revision, build date, and Go version for Chronoctl. Provide this information when reporting an issue with Chronoctl to Chronosphere Support.

chronoctl version

Command autocompletion

You can add support for shell command autocompletion with Chronoctl for the Bash, Zsh, Fish, and PowerShell by using the chronoctl completion command.

This section provides detailed steps for Bash and Zsh on macOS. For Linux-specific details and instructions for Fish and PowerShell, see the output of chronoctl help completion.

You can now press Tab on the command line to automatically complete Chronoctl commands.

Manage v2 alerts

If you still use the deprecated v2 version of alerts, you can still create and manage those alerts with Chronoctl. See Manage v2 alerts with Chronoctl.