flashduty-cli

Flashduty CLI

English | 中文

Flashduty CLI (flashduty) is the official open-source command-line tool for Flashduty, the incident management and on-call platform. From a terminal, a shell script, or an AI coding agent you can triage incidents and alerts, query on-call schedules, publish status page updates, manage monitors and RUM, and drive the AI SRE.

Website · CLI documentation · API reference · Console · Blog: a CLI for humans and agents · Releases

Highlights

• The whole public API. Every public Flashduty API operation has a command, generated from the OpenAPI spec through the go-flashduty SDK. Common workflows (incidents, alerts, on-call, status pages) also get hand-tuned commands with shorter flags and readable tables.
• Predictable names. An API path maps directly to a command: POST /incident/merge is flashduty incident merge, and POST /status-page/change/create is flashduty status-page change-create.
• Built for scripts and agents. Output as table, json, or toon (compact, fewer tokens). List pages are size-bounded and say so when reduced. --fields projects rows to the fields you need.
• One binary. macOS, Linux, and Windows on amd64 and arm64. flashduty update upgrades in place.

Installation

macOS / Linux

curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh

Windows (PowerShell)

irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex

Manual download

Download the archive for your platform from GitHub Releases, extract it, and put the binary on your PATH.

Installer options

Quick start

# 1. Authenticate with an APP key (console: My → APP Key)
flashduty login
flashduty whoami

# 2. Work with incidents
flashduty incident list --since 24h --severity Critical
flashduty incident info <incident_id>
flashduty incident ack <incident_id>
flashduty incident merge <target_id> --source <id1>,<id2>   # sources are closed and kept
flashduty incident close <incident_id>

# 3. Who is on call, and what changed?
flashduty oncall who
flashduty change list --since 2h

# 4. Explore any area
flashduty status-page --help

How to create an APP key is described in the API reference.

Command groups

Run flashduty <group> --help for the commands in a group, and flashduty <group> <command> --help for flags and examples. The CLI documentation walks through the common workflows.

Integration scope

Use flashduty integration … for public integrations managed in the integration center. Use flashduty channel integration-… for dedicated alert integrations owned by one channel:

flashduty integration list --fields integration_id,name,plugin_type
flashduty channel integration-list --channel-id 20001 --fields integration_id,channel_id,name,plugin_type

Public integration instances require integration permissions. Dedicated reads accept Channels Read, Channels Manage, or Integrations Read and require visibility of the owning channel; dedicated writes require Channels Manage and management access to that channel. The shared integration type-list catalog accepts these three read permissions; scoped App Keys must allow integration.api:read:typeList. Choose by ownership, not by the numeric ID. Both use the management App Key, and a permission failure never switches command families. The bundled Agent Skill explains selection, discovery, and confirmed changes.

Request bodies

Generated commands expose each top-level request field as a typed flag, and take the full JSON body through --data (--data - reads stdin). Positional arguments and typed flags override the matching keys in --data, so nested objects and arrays go in --data while scalars stay readable:

flashduty status-page change-create <page_id> --type incident \
  --title "API latency elevated" --status investigating \
  --data '{"updates":[{"status":"investigating","description":"Investigating.","component_changes":[{"component_id":"<component_id>","status":"degraded"}]}]}'

Authentication and configuration

Credentials are resolved in this order:

1. --app-key flag (hidden, for scripting)
2. FLASHDUTY_APP_KEY environment variable
3. ~/.flashduty/config.yaml, written by flashduty login with 0600 permissions

app_key: your_app_key
base_url: https://api.flashcat.cloud

flashduty config show              # Print current config (key masked)
flashduty config set app_key KEY   # Set the APP key
flashduty config set base_url URL  # Override the API endpoint

Global flags

Output formats

• Table (default): aligned columns for people; long fields are truncated unless --no-trunc is set.
• JSON (--json): for jq and scripts, e.g. flashduty incident list --json | jq '.[].title'.
• TOON (--output-format toon): Token-Oriented Object Notation. It drops the keys JSON repeats on every row, so lists cost far fewer tokens. Use it when an LLM or agent reads the output.

Every structured list page is capped at 16 KiB. A page that had to be reduced is reported on stderr, and list envelopes also carry "truncated": true in the payload. With "emitted_rows": N, only the first N rows were returned: re-request with a smaller --limit until the rows you hold reach total. Without it, every row is present but long values were clipped: narrow --fields.

Commands that query a time range print the window they actually sent on stderr, in the local timezone, e.g. note: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now). stdout stays pure json/toon. incident list --progress Triggered,Processing and alert list --active default to the last 30 days when --since is not given, since open records can be older than a day.

An unknown flag or command error lists the closest valid names and the valid choices at that level.

Updating

flashduty update           # Install the latest release in place
flashduty update --check   # Only report whether a newer release exists

Development

Requires Go 1.26+ (see go.mod). golangci-lint is installed by the Makefile.

make build        # Build bin/flashduty
make test         # Run tests with the race detector
make check        # fmt, lint, test, build
make gen-cards    # Regenerate the command fences in skills/flashduty/reference
make check-cards  # Check those fences against the real command tree
make help         # All targets

Generated commands live in internal/cli/zz_generated_*.go and are produced by go run ./internal/cmd/cligen from the OpenAPI spec bundled with go-flashduty. Hand-written commands live next to them. When a hand-written command takes a generated command's name, TestCuratedCommandsCoverRequestFields requires it to still expose every request field of that API.

Related projects

• go-flashduty: Go SDK for the Flashduty API
• flashduty-mcp-server: MCP server for Flashduty
• terraform-provider-flashduty: Terraform provider for Flashduty resources

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request, and note our Code of Conduct.

• Report a bug or request a feature
• Get help and support
• Report a security vulnerability

License

MIT. See LICENSE.