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

Variable	Description	Default
FLASHDUTY_VERSION	Install a specific version (e.g. v1.5.12)	latest
FLASHDUTY_INSTALL_DIR	Install directory	/usr/local/bin (shell), ~\.flashduty\bin (PowerShell)
MIRROR_URL	Release asset mirror (must be https://)	https://static.flashcat.cloud/flashduty-cli

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.

Area	Groups
On-call	incident, alert, alert-event, change, channel, route, oncall, schedule, calendar, integration, webhook, enrichment, field, template, insight, status-page
Monitors	monit, monit-query, datasource
RUM	rum, sourcemap
AI SRE	safari, session, automation
Platform	account, member, person, team, role, audit
CLI	login, whoami, config, update, version, completion

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

Environment variable	Purpose
FLASHDUTY_APP_KEY	APP key
FLASHDUTY_BASE_URL	API endpoint (default https://api.flashcat.cloud)
FLASHDUTY_NO_UPDATE_CHECK=1	Disable the daily background update check
FLASHDUTY_UPDATE_BASE_URL	Mirror used by flashduty update and the update check

Global flags

Flag	Description
--output-format	table (default), json, or toon
--json	Alias for --output-format json
--no-trunc	Do not truncate long fields in table output
--fields	Keep only these comma-separated top-level fields in json/toon output: each row of a list, or the keys of a single record
--base-url	Override the API base URL
--version	Print the version (same as flashduty version)

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.

Dependency	Purpose
go-flashduty	Flashduty API client, generated from the OpenAPI spec
cobra	Command framework
toon-go	TOON output
yaml.v3	Config file
x/term	Masked APP key input

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.