A command-line interface for managing Rootly incidents, alerts, services, teams, on-call schedules, and pulses from the terminal.

Note: This is the successor to rootlyhq/cli (now archived). All pulse functionality from the original CLI is included here.

Features

• Full CRUD for incidents, alerts, services, and teams
• Pulse tracking (rootly pulse create, rootly pulse run)
• On-call schedule queries (list schedules, view shifts, who's on-call)
• Alert action shortcuts (rootly alerts ack, rootly alerts resolve, rootly alerts escalate)
• Custom incident form fields (rootly form-fields list, incidents create/update --field)
• Status-page templates and scheduled-maintenance events
• Multiple output formats: table, JSON, YAML, markdown
• TTY-aware output (table in terminal, JSON when piped)
• Shell completions for bash, zsh, fish, and PowerShell
• Confirmation prompts for destructive operations
• Pagination and server-side filtering

Installation

Homebrew (macOS/Linux)

brew install rootlyhq/tap/rootly-cli

Go Install

go install github.com/rootlyhq/rootly-cli/cmd/rootly@latest

Download Binary

Download the latest release from the Releases page.

Available for Linux (amd64/arm64), macOS (Intel/Apple Silicon), and Windows (amd64).

Build from Source

git clone https://github.com/rootlyhq/rootly-cli.git
cd rootly-cli
make build
./bin/rootly

Configuration

Set your API key via environment variable or config file:

# Environment variable (recommended for CI/scripts)
export ROOTLY_API_KEY="your-api-key"

# Or config file at ~/.rootly-cli/config.yaml

Config file format (~/.rootly-cli/config.yaml):

api_key: "your-api-key"
api_host: "api.rootly.com"  # Optional, defaults to api.rootly.com

Getting an API Key

1. Log in to your Rootly account
2. Navigate to Settings > API Keys
3. Create a new API key with appropriate permissions

Usage

# Incidents
rootly incidents list
rootly incidents list --status=started --severity=critical
rootly incidents get <id>
rootly incidents create --title="Database outage" --severity=critical
rootly incidents create --title="Database maintenance" --kind=scheduled --scheduled-for=2025-06-20T10:00:00Z --scheduled-until=2025-06-20T12:00:00Z
rootly incidents create --title="API degradation" --field="customer_impact=Checkout unavailable, retrying"
rootly incidents update <id> --status=mitigated
rootly incidents update <id> --scheduled-until=2025-06-20T13:00:00Z
rootly incidents update <id> --field="customer_impact=Checkout restored"
rootly incidents create --title="Checkout errors" --services=api-gateway,payments --types=customer-impacting
rootly incidents update INC-123 --services=api-gateway --teams=platform
rootly incidents update INC-123 --types=                # Clears the incident types
rootly incidents delete <id>

# Alerts
rootly alerts list
rootly alerts get <id>
rootly alerts create --summary="High CPU usage" --source=datadog
rootly alerts ack <id>
rootly alerts resolve <id>
rootly alerts escalate <id>
rootly alerts escalate <id> --escalation-policy=<uuid> --level=2
rootly alerts escalate <id> --team=platform              # Page a team on the alert

# Page a team for an incident (links the page to the incident)
rootly incidents escalate INC-123 --team=platform
rootly incidents escalate INC-123 --team=platform --escalation-policy=<uuid> --note="Database is down"

# Services
rootly services list
rootly services get <id>
rootly services create --name="api-gateway"
rootly services update <id> --description="Main API gateway"
rootly services delete <id>

# Custom form fields
rootly form-fields list
rootly form-fields list --format=json

# Status pages and events
rootly status-pages list
rootly status-pages templates list --status-page=<id>
rootly status-pages events create INC-123 --status-page=<id> --status=scheduled --message="Maintenance is scheduled."
rootly status-pages events update <event-id> --status=in_progress
rootly status-pages events resolve <event-id> --status=completed --message="Maintenance is complete."

# Teams
rootly teams list
rootly teams get <id>
rootly teams create --name="Platform"
rootly teams update <id> --color="#FF5733"
rootly teams delete <id>

# On-Call
rootly oncall schedules                     # List schedules
rootly oncall who                           # Who's on-call right now
rootly oncall who --schedule-id=sched-123   # Filter by schedule
rootly oncall who --service-id=svc-456      # Filter by service
rootly oncall shifts                        # View upcoming shifts (7 days)
rootly oncall shifts --days=14              # Next 14 days
rootly oncall shifts --escalation-policy-id=ep-789

# Pulses
rootly pulse create "Deploy v1.2.3"                      # Send a pulse
rootly pulse create "Deploy v1.2.3" -l "version=1.2.3,team=backend"
rootly pulse create "Deploy v1.2.3" -s api-gateway -e production
rootly pulse create "Deploy v1.2.3" --source=ci -r "commit=abc123,pr=456"

# Pulse Run (wrap a command and send pulse with timing + exit code)
rootly pulse run -- make deploy
rootly pulse run --summary="Deploy to prod" -- make deploy
rootly pulse run -s api-gateway -l "env=prod" -- make deploy

Incident Maintenance and Form Fields

incidents create and incidents update accept --kind (normal, test, scheduled, backfilled, or example) and RFC3339 --scheduled-for / --scheduled-until timestamps. Scheduled timestamps are included in incident detail table and markdown output when present.

Use repeatable --field slug=value flags for custom form fields. Text-like fields accept a value directly; select options are matched without regard to case. Repeat a multi_select or checkbox field to choose multiple options. Values can contain commas; quote the whole flag when needed. Run rootly form-fields list to discover field slugs and option values.

rootly incidents create --title="Release" \
  --field="change_summary=DB migration, app deploy" \
  --field=priority=P1 \
  --field="regions=US East" \
  --field="regions=EU West"

Incident Associations

incidents create and incidents update can link an incident to other Rootly records. Each flag takes comma-separated slugs or IDs, like rootly pulse create --services:

Flag	Links	API attribute
--services	Services	service_ids
--types	Incident types	incident_type_ids
--functionalities	Functionalities	functionality_ids
--environments	Environments	environment_ids
--teams	Teams	group_ids
--causes	Causes	cause_ids

On update, only the flags you pass are sent. Each one replaces the incident's current list, and an empty value (--services=) clears it. update accepts a sequential ID such as INC-123 as well as a UUID or slug.

rootly incidents create --title="Checkout errors" --services=api-gateway,payments --types=customer-impacting
rootly incidents update INC-123 --services=api-gateway --teams=platform

Status-Page Templates and Maintenance Statuses

List a status page's templates with rootly status-pages templates list --status-page=<id>. The command supports --page, --page-size, and the standard --format output flag.

status-pages events create and status-pages events update accept incident statuses investigating, identified, monitoring, and resolved, plus scheduled-maintenance statuses scheduled, in_progress, and completed. For status-pages events resolve, --status defaults to resolved; use --status=completed to complete scheduled maintenance.

Resolving an incident does not resolve its status-page events. After incidents update, incidents create or alerts resolve --resolve-incidents leaves an incident resolved, the CLI warns on stderr about any events still open and prints the rootly status-pages events resolve <event-id> command to run. The check is best-effort and never changes the command's output or exit code.

Escalation

rootly alerts escalate <alert-id> escalates an alert using its current policy. Optionally pass --escalation-policy=<uuid> and/or --level=<n> to select a policy or escalation level; levels must be at least 1. The API's error title is shown when escalation cannot proceed.

Pass --team=<slug-or-id> instead to page a team on the existing alert. --team cannot be combined with --level; --escalation-policy adds that policy as an extra paging target.

rootly incidents escalate <incident-id> --team=<slug-or-id> pages a team for an incident. The incident can be a UUID, slug, or sequential ID such as INC-123. It creates an alert that pages the team and links it to the incident. Optional --escalation-policy=<uuid> pages that policy as well, and --note=<text> is sent to the responders as the alert description. If the team was paged but linking the alert failed, the error prints the alert ID; retry only the link with --link-alert=<alert-id> so the team is not paged twice. Alerts already linked to the incident are kept. An unknown team or incident gives a clear error, and the API's error title is shown otherwise. Paging requires Rootly alerting to be enabled for the organization.

Pulse Flags

Flag	Short	Env Var	Description
--labels	-l	ROOTLY_LABELS	Key=value pairs, comma-separated
--services	-s	ROOTLY_SERVICES	Service slugs/IDs, comma-separated
--environments	-e	ROOTLY_ENVIRONMENTS	Environment slugs/IDs, comma-separated
--source		ROOTLY_SOURCE	Source identifier (default: cli)
--refs	-r	ROOTLY_REFS	Reference key=value pairs, comma-separated
--summary		ROOTLY_SUMMARY	Summary (alternative to positional arg)

pulse run also accepts --summary (defaults to the command string) and automatically adds an exit_status label with the command's exit code.

Output Formats

# Table (default in terminal)
rootly incidents list

# JSON (default when piped, or explicit)
rootly incidents list --format=json
rootly incidents list --format=json | jq '.[] | .title'

# YAML
rootly incidents get <id> --format=yaml

# Markdown (for documentation or LLM consumption)
rootly incidents list --format=markdown

Pagination & Filtering

# Pagination
rootly incidents list --page-size=50 --page=2

# Filtering
rootly incidents list --status=started --severity=critical
rootly alerts list --source=datadog
rootly services list --name=api

# Sorting (prefix with - for descending)
rootly incidents list --sort=created_at
rootly incidents list --sort=-created_at

Global Flags

Flag	Short	Env Var	Description
--api-key	-k	ROOTLY_API_KEY	Rootly API key
--api-host		ROOTLY_API_HOST	API host (default: api.rootly.com)
--format			Output format: table, json, yaml, markdown
--debug	-d	ROOTLY_DEBUG	Enable debug output
--quiet	-q	ROOTLY_QUIET	Suppress non-essential output
--no-color			Disable colored output

Command Reference

Command	Subcommands	Aliases
rootly incidents	list, get, create, update, delete, escalate	incident, inc
rootly alerts	list, get, create, update, ack, resolve, escalate	alert, alr
rootly form-fields	list
rootly services	list, get, create, update, delete	service, svc
rootly teams	list, get, create, update, delete	team
rootly oncall	schedules, shifts, who	on-call
rootly pulse	create, run	pulses
rootly status-pages	list, templates list, events list, events create, events update, events resolve	status-page
rootly completion	bash, zsh, fish, powershell
rootly version

Shell Completions

# Bash
rootly completion bash > /etc/bash_completion.d/rootly

# Zsh
rootly completion zsh > "${fpath[1]}/_rootly"

# Fish
rootly completion fish > ~/.config/fish/completions/rootly.fish

Development

Prerequisites

• Go 1.24+
• Make

Build & Test

make build      # Build binary
make test       # Run tests
make lint       # Run linter
make check      # Format, lint, and test
make coverage   # Tests with coverage report
make coverage-check # Check total statement coverage against the floor

Release

Releases are automated via GoReleaser when a new tag is pushed:

make release-patch   # v0.1.0 -> v0.1.1
make release-minor   # v0.1.0 -> v0.2.0
make release-major   # v0.1.0 -> v1.0.0

License

MIT License - see LICENSE for details.