Root commands

Reading time: 0 minute(s) (0 words)

The sloctl command-line interface provides powerful tools for managing service level objectives using a code-driven approach. This comprehensive guide walks you through essential root commands for configuring, applying, and managing your SLOs as code with the Nobl9 CLI. Whether you're a DevOps engineer, SRE, or platform engineer, mastering these commands will enable you to automate reliability workflows, integrate SLOs into your CI/CD pipeline, and efficiently manage your reliability targets across projects and environments.

sloctl help (start screen)

help is an entry point to working with sloctl. It provides the summary for all available commands, flags, and usage patterns. The following variations of the help command are available:

sloctl
sloctl -h
sloctl --help

Run sloctl [command] --help for detailed information about any specific command, including all available options and example usage scenarios.

Syntax

sloctl [command] --help

sloctl apply

The apply command is the primary method for committing SLO definitions to your Nobl9 environment. It supports a declarative workflow—you define your reliability targets in YAML or JSON files and apply them programmatically.

The -f or --file flag is central to the apply command's functionality. With it, you can specify configuration files in the following ways:

• Individual or multiple files
• URLs
• Standard input
• Glob patterns

sloctl extends Go glob patterns with additional capabilities:

• Supports '**' for recursive file processing
• Processes files with .yaml, .yml, and .json extensions
• Pre-validates files for Nobl9 API version with regex: "?apiVersion"?\s*:\s*"?n9

Glob patterns usage requirement

When using glob patterns, always enclose them in quotes to prevent shell evaluation.

sloctl apply key points

• Default threshold of 23 files before confirmation prompt
• Automatic confirmation with the -y flag
• Customizable thresholds and confirmation prompt with environmental variables

Syntax

sloctl apply <object> [flags]

Available objects

Object	Description
agents	Apply data sources connected using the agent method
alertmethods	Apply alert methods
alertpolicies	Apply alert policies
alertsilences	Silence alerts
alerts	Apply alert events
annotations	Apply annotations
budgetadjustments	Apply budget adjustment definitions
dataexports	Apply exported CSVs
directs	Apply data sources connected using the direct method
projects	Apply projects
rolebindings	Apply role bindings
services	Apply services
slos	Apply SLOs

Flags

Flag	Shorthand	Description
--dry-run	N/A	Submits server-side request without persisting the configured resources. Can be used for testing a YAML definition
--file	-f	Provide a file path, glob pattern or a URL to YAML or JSON configuration. Can be used multiple times
--from	N/A	Specify the start of the historical data retrieval for Replay (RFC3339 format)
--replay	N/A	Run Replay for applied SLOs. If mixed resources are applied (projects, data sources, SLOs, etc.), only SLOs will be replayed. If Replay fails, specified resources will still be applied
--yes	-y	Auto confirm files threshold prompt

Example usage

Command	Description
sloctl apply -f ./my-slo.yaml	Apply a single configuration file
sloctl apply -f ./my-agent.yaml	Apply an agent configuration for deployment
sloctl apply -f ./my-slo.yaml -f test/config.yaml -f https://my-definition.com/slo.yaml	Apply resources from multiple sources
sloctl apply -f ./my-slo.yaml -p my-project	Apply a configuration file with project fallback if not defined in the file
sloctl apply -f '**'	Apply configurations from all files located in a current directory (recursively)
sloctl apply -y -f '**'	Apply and confirm applying multiple resources
sloctl apply -f '**/annotations*'	Apply the configurations from files with annotations in names accross all directories
sloctl apply -f ./slo.yaml --replay --from=2025-03-02T15:00:00Z	Apply SLO(s) and import their historical data from specific timeframe (2025-03-02T15:00:00Z – now)
cat my-slo.yaml | sloctl apply -f -	Apply configuration from stdin

--dry-run with --replay

Combining these flags prevents Replay from running.

sloctl aws-iam-ids

The sloctl aws-iam-ids command retrieves authentication identifiers needed for integrating with AWS services. Use this to obtain your External IAM ID and the Nobl9 AWS Account ID required for setting up Amazon CloudWatch data sources with Cross-account resource access in IAM.

Syntax

sloctl aws-iam-ids <object>

Available objects

Object	Description	Example usage
dataexport	Returns an AWS External ID that Nobl9 uses to assume the IAM role for data export operations	sloctl aws-iam-ids dataexport [global-flags]
direct	Returns the external ID and AWS account ID for a specified direct integration with a data source	sloctl aws-iam-ids direct my-cloudwatch-source [flags]

Flags

The direct object supports additional flags:

Flag	Shorthand	Description
--field-separator	N/A	Field separator for exported CSV (default: ",")
--output	-o	Output format yaml | json | csv Default: yaml

Output examples

When using the direct subcommand with default output format:

# Example output
externalId: a1b2c3d4-5678-90ab-cdef-ghijklmnopqr
accountId: 123456789012

When to use each subcommand

• Use dataexport when setting up permissions for Nobl9 to export data to your AWS services
• Use direct when configuring a CloudWatch data source to provide metrics to Nobl9

sloctl budgetadjustments events

Use the budgetadjustments events family to manage events associated with budget adjustments in your SLOs. These commands allow you to retrieve, update, or delete budget adjustment events.

With this command, you can handle budget adjustment events that correspond to your specified subcommands.

The subcommands are as follows:

• Get adjustments: sloctl budgetadjustments events get
• Update adjustments: sloctl budgetadjustments events update
• Delete adjustments: sloctl budgetadjustments events delete

Syntax

sloctl budgetadjustment events [command] [flags]

Flags

Flag	Shorthand	Description	Required
--adjustment-name	N/A	Event name identifier	Required for all subcommands
--from, --to	N/A	Start and end timestamps	Required for get subcommands
--slo-name, --slo-project	N/A	SLO and its enclosing project name identifiers	Optional filters for get subcommands
--file	-f	Path to the YAML file with your target event	Required for update and delete subcommands

Get budget adjustment events

Run sloctl budgetadjustments events get to retrieve events for a specified adjustment and its related SLOs. When executed, the command returns:

• Past and ongoing events (up to 250 events)
• SLOs associated with the requested adjustment event
• Results sorted chronologically by event start time

You can filter response by a single SLO per request. Then, the response contains events related to the specified SLO.

sloctl and past budget adjustment events

To manage past budget adjustment events, update your sloctl to version 0.9.0 or higher.

Flags

Flag	Description	Required
--adjustment-name	The name identifier of the adjustment	Required
--from	Start of the time range (UTC)	Required
--to	End of the time range (UTC)	Required
--slo-project	Project name of the SLO	Required for --slo-name
--slo-name	SLO name to filter events	Optional

Example usage

Command	Description
sloctl budgetadjustments events get --adjustment-name=my-adjustment --from=2024-09-23T00:45:00Z --to=2024-09-23T20:46:00Z	Get budget adjustment events: For My adjustment event Happened between September 23, 2024 00:45 UTC and September 23, 2024 20:46 UTC
sloctl budgetadjustments events get --adjustment-name=my-adjustment --from=2024-09-23T00:45:00Z --to=2024-09-23T20:46:00Z --slo-project=my-project--slo-name=my-slo	Get budget adjustment events: For the My adjustment event Happened to My SLO from My project between September 23, 2024 00:45 UTC and September 23, 2024 20:46 UTC

Update and delete budget adjustment events

You can update and delete existing past adjustment events. For this, prepare a YAML file with your modifications and pass it with the required subcommand:

• sloctl budgetadjustments events update
• sloctl budgetadjustments events delete

Example usage

Update

1. Prepare a YAML file following this sample:

   Sample YAML to update budget adjustment events

   - eventStart: 2024-10-24T04:07:04Z
     eventEnd: 2024-10-24T05:27:04Z
     slos:
     - project: customer-facing-applications
       name: profile-page-availability
     update:
       eventStart: 2024-10-24T03:07:04Z
       eventEnd: 2024-10-24T04:27:04Z
   - eventStart: 2024-10-25T04:07:04Z
     eventEnd: 2024-10-25T05:27:04Z
     slos:
     - project: backend-services
       name: database-latency
     update:
       eventStart: 2024-10-25T03:07:04Z
       eventEnd: 2024-10-25T04:27:04Z

2. Run the update command using a file path:

   sloctl budgetadjustments events update --adjustment-name=my-adjustment -f ./modified-events.yaml

   Or using standard input:

   sloctl budgetadjustments events update --adjustment-name=my-adjustment -f - <./modified-events.yaml

Delete

1. Prepare a YAML file following this sample:

   Sample YAML to delete a budget adjustment event

   - eventStart: 2024-01-27T00:00:00Z
     eventEnd: 2024-01-27T02:00:00Z
     slos:
       - project: response-time
         name: latency-slo
       - project: continuous-service
         name: uptime-slo

2. Run:

   sloctl budgetadjustments events delete --adjustment-name=my-adjustment -f ./events-to-delete.yaml

   Or using standard input:

   sloctl budgetadjustments events delete --adjustment-name=sample-adjustment-name -f - < ./events-to-delete.yaml

Flags

Flag	Shorthand	Description	Required
--adjustment-name	N/A	The name identifier of the adjustment	Required
--file	-f	Path to the YAML file with event details or updates	Required

Budget adjustment event vs. definition

Handling budget adjustments in Nobl9 relies on two concepts:

• Budget adjustment definition
• Budget adjustment events

To handle budget adjustment definitions, use sloctl root commands, like sloctl apply or sloctl delete, specifying the budgetadjustments object with your required budget adjustment name identifier.

To handle budget adjustment events, use the sloctl budgetadjustments events command, specifying the required operation, like update or delete, as a subcommand.

sloctl completion

Run sloctl completion to generate the autocompletion script for sloctl for the specified shell.

Syntax

sloctl completion <object>

Available objects

Object	Description
bash	Generate the autocompletion script for bash
fish	Generate the autocompletion script for fish
powershell	Generate the autocompletion script for PowerShell
zsh	Generate the autocompletion script for zsh

sloctl config

Use sloctl config commands to handle your access profiles—contexts—stored in your configuration file.

A context includes access parameters:

• Client ID
• Client secret
• Default project

Syntax

sloctl config [command] <flags>

Commands

Command	Description	Example
add-context	Add a new configuration context. Once all set, you can set your new context as default. Pressing Enter without selecting y or n defaults to n.	sloctl config add-context
current-context	Display the name of your current context	sloctl config current-context
delete-context	Delete a specified context in the configuration file. Bulk deletion is unavailable.	sloctl config delete-context my-context
get-contexts	Display available context names	sloctl config get-contexts my-context -v
rename-context	Rename a context in your configuration file. Provide your existing context name and the desired name for this context. Bulk renaming is unavailable.	sloctl config rename-context my-context my-renamed-context
use-context	Set a current context. Provide your required context name to set it as current. Without arguments, sloctl lists all available contexts. Specify the required context name and press Enter.	sloctl config use-context my-context

Flags

Flag	Shorthand	Description
--verbose	-v	Available for current-context and get-contexts. Expand the context details with: Current context name Your client ID Your client secret (hidden) The default project name

sloctl convert

Run sloctl convert to convert your OpenSLO definition to the Nobl9-compatible format. Once converted, run sloctl apply to import the converted resource to Nobl9 and leverage the applicable Nobl9 tools and insights for reliability monitoring.

Syntax

sloctl convert openslo [flags]

Flags

Flag	Shorthand	Description
--file	-f	File path, glob pattern or a URL to the configuration in the YAML or JSON format. You can use this flag several times within the same command
--output	-o	Output file format, one of: yaml | json | csv. Default: yaml

Example usage

Command	Description
sloctl convert openslo -f ./my-slo.yaml	Convert my-slo.yaml
sloctl convert openslo -f ./my-project.yaml -f ./my-service.yaml	Convert my-project.yaml and my-service.yaml in bulk
sloctl convert openslo -f - <my-slo.yaml	Convert my-slo.yaml passed directly in standard input
sloctl convert openslo -f '**'	Convert all OpenSLO definitions located in cwd recursively
sloctl convert openslo -f '**/latency*'	Convert all OpenSLO definitions with latency in their names located within the directory
sloctl convert openslo -f ./my-slo.yaml | sloctl apply -f -	Convert my-slo.yaml and apply the configuration with one command

sloctl delete

Use the sloctl delete command to remove existing resources. The -f or --file flag is central to the delete command's functionality. With it, you can delete files in the following ways:

• Individual or multiple files
• URLs
• Standard input
• Glob patterns

sloctl extends Go glob patterns with additional capabilities:

• Supports '**' for recursive file processing
• Processes files with .yaml, .yml, and .json extensions
• Pre-validates files for the Nobl9 API version with regex: "?apiVersion"?\s*:\s*"?n9

Glob patterns usage requirement

When using glob patterns, always enclose them in quotes to prevent shell evaluation.

Syntax

  sloctl delete <object> [flags]

Available objects

Object	Description
agents	Delete data sources connected using the agent method
alertmethods	Delete alert methods
alertpolicies	Delete alert policies
alertsilences	Resume silenced alerts
alerts	Delete alert events
annotations	Delete annotations
budgetadjustments	Delete budget adjustment definitions
dataexports	Delete exported CSVs
directs	Delete data sources connected using the direct method
projects	Delete projects
rolebindings	Delete role bindings
services	Delete services
slos	Delete SLOs

Flags:

Flag	Shorthand	Description
--file	-f	Provide a file path, glob pattern or a URL to the configuration in YAML or JSON format. This option can be used multiple times
--yes	-y	Auto confirm files threshold prompt

Example usage

Command	Description
sloctl delete slo my-slo	Delete an SLO using the SLO name
sloctl delete -f ./my-slo.yaml	Delete a single configuration file
sloctl delete -f ./my-agent.yaml	Delete an agent
sloctl delete -f ./my-slo.yaml -f test/config.yaml -f https://my-definition.com/slo.yaml	Delete resources from multiple sources
sloctl deletee -f ./my-slo.yaml -p my-project	Delete a configuration file with project fallback if not defined in the file
sloctl delete -f '**'	Delete configurations from all files located in a current directory (recursively)
sloctl delete -y -f '**'	Delete and confirm deletion of multiple resources
sloctl delete -f '**/annotations*'	Delete the configurations from files with annotations in names across all directories
cat my-slo.yaml | sloctl delete -f -	Delete a configuration YAML from stdin

sloctl get

Run sloctl get to retrieve and display information about specific objects managed by sloctl. You can query a variety of resources and receive data about their current state.

System annotations

sloctl doesn't return system annotations. When applying the sloctl get annotation[s] command, sloctl will return only annotations created by the user.

Syntax

  sloctl get <object> [flags]

sloctl get alertpolicies

In Nobl9 release 1.66.2-3, the response from sloctl get alertpolicies is deprecated, and will be phased out in the future.

After that, for the alertMethods object, the command will return only the metadata.name and metadata.project fields associated with the alert policy:

apiVersion: n9/v1alpha
kind: AlertPolicy
metadata:
  ...
spec:
  ...
  alertMethods:
    - metadata:
        name: my-alert-method
        project: my-project

We'll inform you about the full phase-out in a separate announcement

Flags:

Flag	Shorthand	Description
--labels	-l	Filter resources by label. For example: key=value,key2=value2,key2=value3
-output	-o	Specify the output format. One of: table | yaml | json. Default yaml
--with-keys	-k	Retrieve client_secret and client_id for agents in your default project. Available for sloctl get agents only. To retrieve keys for all agents in the organization, add the -A flag: sloctl get agents -Ak

client_id and client_secret

To get client_id and client_secret, Nobl9 sends a request for every agent in your organization. It means that every additional Nobl9 agent in your organization increases the waiting time for a response from sloctl.

Example usage

Command	Description
sloctl get slo streaming-other-slo streaming-latency-slo	Get several SLOs (separate name identifiers with space)
sloctl get agents -Ak	Get client credentials for agents in all projects
sloctl get agents my-agent-1 my-agent-2	Get client credentials for my-agent-1 and my-agent-2 agents specifically

• When you run sloctl get providing a resource type without a specific resource name, sloctl returns all available objects in the default project.
• When you run sloctl get providing a resource type and the required resource name, sloctl returns the YAML configuration of the requested resource.
• To get a resource from a project other than the default, specify the required project using the -p (--project) flag.

sloctl get alerts

Get alerts based on the search criteria. sloctl returns up to 1000 alerts as follows:

• Alerts related to a specific SLO, objective, service, or alert policy within the specified project
• Alerts from your default project when no project is specified
• No alerts when you lack access to the specified project

You can use different flags in one command or the same flag several times. The filter logic is as follows:

• Different flags: sloctl returns alerts matching all specified criteria (AND logic)
• Same flag several times: sloctl returns all matching alerts (OR logic)

Syntax

sloctl get alerts <flags>

Aliases:

alerts, alert

Reasons why sloctl returns no alerts

sloctl returns alerts only for existing objects (alert policies, SLOs, services, and objectives):

• A related resource has been deleted
• A related resource was deleted and later recreated with the same name
• An alert policy with qualifying alerts has been unlinked from the SLO you are requesting alerts for

Flags

Flag	Description
--alert-policy	Get alerts for a given alert policy
--from	Get alerts after from time, based on metric timestamp (RFC3339), for example 2023-02-09T10:00:00Z
--objective	Get alerts for a given SLO objective
--resolved	Get resolved alerts
--service	Get alerts for SLOs in a given service
--slo	Get alerts for a given SLO
--to	Get alerts before to time, based on metric timestamp (RFC3339), for example 2023-02-09T10:00:00Z
--triggered	Get unresolved alerts

Example usage

Command	Description
sloctl get alert -A	Get all alerts across all projects in your organization
sloctl get alert --triggered -A	Get unresolved alerts
sloctl get alert XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX	Get alert details by its name identifier. If this alert isn't in your default project, specify the project with the -p (--project) flag. Alternatively, add the -A flag to allow search across all projects
sloctl get alert --service authorization-page --service orders-and-payments -p customer-facing-applications	Get alerts related to the authorization-page and orders-and-payments services in the customer-facing-applications project
sloctl get alert --resolved --alert-policy slow-burn --slo usersapi -p customer-facing-applications	Get resolved alerts related to the slow-burn alert policy, userapi SLO in the customer-facing-applications project
sloctl get alert --slo usersapi --objective acceptable -p customer-facing-applications	Get alerts for the acceptable objective of the userapi SLO in the customer-facing-applications project
sloctl get alert --slo usersapi --objective acceptable --objective excellent -p customer-facing-applications	Get alerts for the acceptable and excellent objectives of the userapi SLO in the customer-facing-applications project
sloctl get alert --from 2025-03-22T00:00:00Z --to 2025-03-22T23:59:59Z -A	Get alerts across all projects for the period from Mar 22 2025 00:00:00 to Mar 22 2025 23:59
sloctl get alert --from <a timestamp> -A	Get alerts across all projects from the timestamp till now
sloctl get alert --to 2025-03-22T00:00:00Z -A	Get alerts across all projects until Mar 22, 2025 00:00

Additional alert details

sloctl returns detailed information about alerts triggered or resolved on the spec level. Run sloctl get alerts to see data for each condition, including the time of its onset (corresponds to the yellow interval in the alert chart), how long it lasted, and when it was last met. For Resolved alerts, you can see when the cooldown period started and the reason for the resolution. If an alert was canceled, the reason for cancellation is included as well.

Specification	Description
spec.conditions[].status.FirstMetMetricTime	The time at which the condition was first met, indicating when the metric value crossed the alert threshold for the first time.
spec.conditions[].status.LastsForMetMetricTime	The duration for which the condition was met, even if the "lasts for" parameter is set to 0 minutes.
spec.conditions[].status.LastMetMetricTime	The time at which the condition was last met, indicating when the metric value stopped meeting the alert threshold.
spec.coolDownStartedAtMetricTime	The time at which the cooldown period started, applicable only for resolved alerts.
spec.resolutionReason	The reason for resolution, particularly noteworthy for understanding why the alert was canceled.

sloctl replay

Run sloctl replay to replay SLOs. Before replaying an SLO, it verifies the possibility to replay SLOs. Unlike sloctl apply --replay, this command allows you to replay existing SLOs.

Replaying SLOs is a permanent action

Replaying SLOs is a permanent action and cannot be rolled back.

When Replay fails, it proceeds with the next SLO. Replaying SLOs takes time: one Replay job may take several minutes up to an hour. Job cancelling or changing currently replayed SLOs don't impact an ongoing Replay.

🧪sloctl version requirements

We recommend updating sloctl to these versions or higher for the following functionality:

• Version 0.3.0: replaying composite SLOs
• Version 0.6.0: replaying SLOs from other SLOs (experimental)
• Version 0.8.0: Replay queue management

Syntax

sloctl replay [command] <flags>

sloctl replay requires three parameters:

• SLO name identifier
• SLO's parent project
• A from timestamp to define the replayed period

You can pass these parameters in one command as shown in the Syntax example. Alternatively, you can prepare a Replay YAML definition that outlines your requirements and run sloctl replay for this YAML. The YAML definition must follow the pattern provided below:

# SLO name identifier (the lease requirement). The provided SLO must be in your default project, the timestamp must be passed with the --from flag
- slo: response-rate
# SLO and project name identifier and the timestamp. Project and timestamp from this definition take priority over the flags.
- slo: response-rate
- project: customer-facing-applications
- from: 2025-04-07T00:00:00Z

Flags:

Flag	Shorthand	Description
--file	-f	Provide a file path, glob pattern or a URL to the configuration in YAML or JSON format. This option can be used multiple times
--from	N/A	Specify the start of the historical data retrieval (RFC3339 format)

Example usage

Command	Description
sloctl replay my-slo --from=2025-04-07T00:00:00Z	Replay the my-slo SLO in the default project from Apr 07, 2025 00:00 UTC until now
sloctl replay -f ./slos-to-replay.yaml	Replay SLOs from the list of SLOs and for the period as specified in the slos-to-replay.yaml. When the SLO's parent project isn't provided in slos-to-replay.yaml, sloctl will search for specified SLOs within your default project
sloctl replay <./slos-to-replay.yaml	Replay SLOs from stdin
sloctl replay -p customer-facing-applications --from=2025-04-07T00:00:00Z error-rate	Replay the error-rate SLO in the customer-facing-applications starting from Apr 07, 2025, 00:00 UTC until now

Project and timestamp priority

You can specify the project and timestamp in your Replay YAML definition and pass them as flags as well. When using both, project and timestamp from the YAML definition take priority over the flags.

sloctl version

The version command prints the installed version of sloctl.

Usage:

  sloctl version

The response includes your current sloctl version, the operating system, processor architecture, and the runtime version used to compile the binary.