Command-line tool

Overview

Flashduty CLI (flashduty) is a command-line tool for managing the incident lifecycle, querying on-call schedules, publishing status page updates, and debugging notification templates from your terminal. It fits naturally into operations scripts, local troubleshooting, and AI coding-agent workflows. The tool is open source at flashcatcloud/flashduty-cli and supports macOS, Linux, and Windows.

Installation

macOS / Linux
Windows (PowerShell)
Manual download

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

Installs to /usr/local/bin by default. Override with the FLASHDUTY_INSTALL_DIR environment variable.

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

Installs to ~\.flashduty\bin by default. Override with the FLASHDUTY_INSTALL_DIR environment variable.

Read the latest version from the CDN latest version pointer, then download the matching asset from https://static.flashcat.cloud/flashduty-cli/releases/download/<version>/<asset>, extract it, and place it on your PATH.

Installer options

Variable	Description	Default
`FLASHDUTY_VERSION`	Install a specific version, e.g. `v0.6.0`	latest
`FLASHDUTY_INSTALL_DIR`	Custom install directory	`/usr/local/bin` (shell), `~\.flashduty\bin` (PowerShell)

Authentication

Log in

flashduty login

When prompted, paste your APP Key. To obtain one, sign in to the Flashduty console and copy your APP Key from Profile > Personal Info.

Credential resolution order

The CLI resolves credentials in the following order (highest priority first):

--app-key command-line flag (hidden, for scripting)
FLASHDUTY_APP_KEY environment variable
Config file ~/.flashduty/config.yaml (written by flashduty login)

Config file

Stored at ~/.flashduty/config.yaml with 0600 permissions:

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

Config commands

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

Global flags

All subcommands accept these flags:

Flag	Description
`--output-format`	Output format: `table` (default), `json`, or `toon` (compact, token-efficient)
`--json`	Alias for `--output-format json`; emit JSON for parsing with `jq` or similar tools
`--no-trunc`	Disable column truncation in table output
`--base-url`	Override the API endpoint (for private deployments)

Command catalog

incident — Incident lifecycle

flashduty incident list [flags]          # List incidents (default: last 24h)
flashduty incident get <id> [<id2>...]   # Show incident details (vertical view for a single ID)
flashduty incident create [flags]        # Create an incident (interactive if flags are missing)
flashduty incident update <id> [flags]   # Update incident fields
flashduty incident ack <id> [<id2>...]   # Acknowledge incidents
flashduty incident close <id> [<id2>...] # Close (resolve) incidents
flashduty incident timeline <id>         # View an incident timeline
flashduty incident alerts <id>           # List alerts associated with an incident
flashduty incident similar <id>          # Find similar historical incidents

Common filter flags for incident list:

Flag	Description	Default
`--progress`	Progress filter: `Triggered`, `Processing`, `Closed`	all
`--severity`	Severity filter: `Critical`, `Warning`, `Info`	all
`--channel`	Filter by channel ID	-
`--title`	Search by title keyword	-
`--since`	Start time (duration, date, datetime, or unix timestamp)	`24h`
`--until`	End time	`now`
`--limit`	Max results	`20`
`--page`	Page number	`1`

Time format examples: 5m, 1h, 24h, 168h, 2026-04-01, 2026-04-01 10:00:00, 1712000000.

change — Change records

flashduty change list [flags]    # List change records (deployments, config changes)

Supports --channel, --since, --until, --type, --limit, --page.

member — Member queries

flashduty member list [flags]    # List members

Supports --name, --email, --page.

team — Team queries

flashduty team list [flags]      # List teams with members

Supports --name, --page.

channel — Channel queries

flashduty channel list [flags]   # List channels

Supports --name.

escalation-rule — Escalation rule queries

flashduty escalation-rule list --channel <id>          # By channel ID
flashduty escalation-rule list --channel-name <name>   # By channel name (auto-resolved)

field — Custom field queries

flashduty field list [flags]     # List custom field definitions

Supports --name.

statuspage — Status page management

flashduty statuspage list [--id <ids>]                                   # List status pages
flashduty statuspage changes --page-id <id> --type <incident|maintenance> # List active changes
flashduty statuspage create-incident --page-id <id> --title <title>      # Create a status page incident
flashduty statuspage create-timeline --page-id <id> --change <id> --message <msg>  # Append a timeline update

Migrate from Atlassian Statuspage

Migration jobs run asynchronously. After kicking off a job, poll progress with migrate status:

# 1. Migrate structure and history
flashduty statuspage migrate structure \
  --from atlassian \
  --source-page-id page_123 \
  --api-key $ATLASSIAN_STATUSPAGE_API_KEY

# 2. Check job status
flashduty statuspage migrate status --job-id <job_id>

# 3. Migrate email subscribers
flashduty statuspage migrate email-subscribers \
  --from atlassian \
  --source-page-id page_123 \
  --target-page-id <target_page_id> \
  --api-key $ATLASSIAN_STATUSPAGE_API_KEY

# 4. Cancel a running job
flashduty statuspage migrate cancel --job-id <job_id>

template — Notification templates

flashduty template get-preset --channel <channel>             # Get preset template code
flashduty template validate --channel <channel> --file <path> # Validate and preview a template
flashduty template variables [--category <category>]          # List available template variables
flashduty template functions [--type custom|sprig|all]        # List available template functions

Supported channels: dingtalk, dingtalk_app, feishu, feishu_app, wecom, wecom_app, slack, slack_app, telegram, teams_app, email, sms, zoom.

session — AI SRE sessions

Inspect AI SRE (and other Flashduty agent) sessions: session list lists the sessions visible to the caller, and session export streams a single session’s full event log for offline analysis.

flashduty session list [flags]            # List agent sessions (sorted by updated_at desc, newest first)
flashduty session export <session_id>     # Stream a single session's full events as NDJSON

Common flags for session list:

Flag	Description	Default
`--app`	Which agent app’s sessions to list	`ai-sre`
`--scope`	Visibility: `all` (your own + your teams, default), `personal`, `team`	`all`
`--status`	Archive status: `active` (default), `archived`, `all`	`active`
`--team-id`	Keep only sessions for the given team ID	-
`--since`	Keep only sessions updated within the window (client-side filter), e.g. `30d`, `24h`, `2026-05-01`	-
`--limit`	Max sessions to fetch	`200`
`--page`	Start page (1-based)	`1`
`--format`	Output format: `jsonl` (default, one session object per line, pipe straight to `jq`), `json` (full envelope), `toon` (compact)	`jsonl`

The server endpoint /safari/session/list caps each page at 100 rows; when --limit exceeds that, the CLI paginates automatically — no manual paging required. The API has no time-window filter, so --since is applied client-side against each session’s updated_at after fetching.

session export streams session events as newline-delimited JSON (NDJSON) to stdout: the first line is always a session_meta envelope, and each subsequent line is one event (user_message, llm_call, tool_call, subagent_dispatch, final_answer, agent_text, error). Exports can be large, so redirect to a file instead of printing to the terminal:

flashduty session export <session_id> > session.ndjson
flashduty session export <session_id> --include-subagents > session.ndjson

Flag	Description
`--include-subagents`	After each `subagent_dispatch`, recursively inline that subagent’s own full event stream

Full command coverage

Beyond the curated commands above, the CLI now provides full coverage of the Flashduty OpenAPI (~248 commands) via a spec-driven code generator, organized into top-level command groups by resource. In addition to the On-call domain (incident, change, channel, escalation-rule, field, statuspage, template, and more), it also covers:

AI SRE (safari): a2a-agents, mcp-servers, sessions, skills, and more
Alerting & noise reduction: alert, alert-event, enrichment (alert-rules, rule-sets), route
On-call & scheduling: calendar, schedule
Platform administration: account, member, person, team, role (roles-permissions), audit (audit-logs)
Monitoring & RUM: monit, rum, sourcemap
Integrations & webhooks: datasource (IM integrations), webhook (integrations)

These generated leaf commands use a resource-action naming form (e.g. flashduty safari a2a-agent-get, flashduty safari session-list); their inputs and response fields map directly to the corresponding API. Explore them level by level with flashduty <resource> --help:

flashduty --help                 # List all top-level command groups
flashduty safari --help          # AI SRE generated commands
flashduty alert --help           # Alert-related generated commands

Utility commands

flashduty login          # Interactive login
flashduty config show    # Show current configuration
flashduty config set     # Set a configuration value
flashduty version        # Print version information
flashduty completion     # Generate shell completions (bash/zsh/fish/powershell)

Enable shell completion (zsh example):

flashduty completion zsh > "${fpath[1]}/_flashduty"

Output formats

Select the output shape with --output-format (--json is an alias for --output-format json) to fit different consumers:

Table (default)
JSON (--json / --output-format json)
TOON (--output-format toon)
Full table (--no-trunc)

Human-readable, aligned columns, long fields truncated.

ID           TITLE                    SEVERITY   PROGRESS     CHANNEL       CREATED
inc_abc123   DB connection timeout    Critical   Triggered    Production    2026-04-10 10:23
inc_def456   High memory usage        Warning    Processing   Staging       2026-04-10 09:15
Showing 2 results (page 1, total 2).

Machine-parseable, full payload, no truncation. Ideal for scripts and CI/CD pipelines.

flashduty incident list --json | jq '.[].title'

TOON (Token-Oriented Object Notation) emits the full payload without truncation, but for homogeneous arrays it drops the per-row field names that JSON repeats — cutting token usage substantially on list output, which suits feeding to AI agents.

flashduty incident list --output-format toon

TOON cannot be parsed directly by jq; use --json when you need to pipe into jq.

Agent skills

Flashduty CLI ships with 10 agent skills that teach AI coding agents — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and 40+ others — how to operate Flashduty from your terminal. Install skills to every detected agent on your machine in one shot:

npx skills add flashcatcloud/flashduty-cli -y -g

Available skills:

Skill	Scope
`flashduty-shared`	Foundation: authentication, three-layer noise model, global flags, safety rules
`flashduty-incident`	Incident lifecycle: triage, investigate, resolve, merge, snooze, reassign
`flashduty-alert`	Alert and alert event investigation: drill down, trace, merge
`flashduty-change`	Change event tracking and deployment frequency trends
`flashduty-oncall`	On-call schedule queries: who is on call, shift details
`flashduty-channel`	Channel and escalation rule lookups
`flashduty-statuspage`	Status page management and Atlassian → Flashduty migration
`flashduty-insight`	Analytics: MTTA/MTTR, noise reduction, notification trends
`flashduty-admin`	Team/member lookups and audit log search
`flashduty-template`	Notification template validation and preview

Common workflows

Attach a CLI link to notifications

Use flashduty incident get <id> to fetch incident details from the terminal. Embed the snippet into notification templates so responders can copy-paste it.

Bulk acknowledge or close incidents

flashduty incident ack inc_001 inc_002 inc_003
flashduty incident close inc_001 inc_002 inc_003

Export incident data to BI tools

flashduty incident list --since 168h --limit 500 --json > incidents.json

Then process the file with jq or load it into your warehouse.

Validate notification templates in CI/CD

flashduty template validate --channel feishu --file templates/feishu.yaml

Run this in CI to catch syntax or field errors as soon as a template is committed.

Full source and issue tracking live on the GitHub repository.

Home

Products

Platform

Developer

Compliance

Changelog

Overview

Installation

Installer options

Authentication

Log in

Credential resolution order

Config file

Config commands

Global flags

Command catalog

incident — Incident lifecycle

change — Change records

member — Member queries

team — Team queries

channel — Channel queries

escalation-rule — Escalation rule queries

field — Custom field queries

statuspage — Status page management

Migrate from Atlassian Statuspage

template — Notification templates

session — AI SRE sessions

Full command coverage

Utility commands

Output formats

Agent skills

Common workflows

​Overview

​Installation

​Installer options

​Authentication

​Log in

​Credential resolution order

​Config file

​Config commands

​Global flags

​Command catalog

​incident — Incident lifecycle

​change — Change records

​member — Member queries

​team — Team queries

​channel — Channel queries

​escalation-rule — Escalation rule queries

​field — Custom field queries

​statuspage — Status page management

​Migrate from Atlassian Statuspage

​template — Notification templates

​session — AI SRE sessions

​Full command coverage

​Utility commands

​Output formats

​Agent skills

​Common workflows

Overview

Installation

Installer options

Authentication

Log in

Credential resolution order

Config file

Config commands

Global flags

Command catalog

incident — Incident lifecycle

change — Change records

member — Member queries

team — Team queries

channel — Channel queries

escalation-rule — Escalation rule queries

field — Custom field queries

statuspage — Status page management

Migrate from Atlassian Statuspage

template — Notification templates

session — AI SRE sessions

Full command coverage

Utility commands

Output formats

Agent skills

Common workflows