Skip to content

README.md

Latest commit

 

History

History
189 lines (135 loc) · 9.8 KB

README.md

File metadata and controls

189 lines (135 loc) · 9.8 KB
Raw

Flashduty CLI

English | 中文

License Release CI Go Report Card

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

Contributing

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

License

MIT. See LICENSE.