Command-line tool - Flashduty Docs

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)
`MIRROR_URL`	Override the release asset download mirror prefix used by the installer script; must use `https://`	`https://static.flashcat.cloud/flashduty-cli`
`FLASHDUTY_UPDATE_BASE_URL`	Override the base URL used by `flashduty update` and the automatic update check	`https://static.flashcat.cloud/flashduty-cli`

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	-
`--query`	Free-text search across title, labels, and content (also resolves a 24-char incident ID or 6-char incident num to a direct lookup)	-
`--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.

Work items and follow-ups (work-item-*)

incident work-item-* manages work items anchored to an incident or a post-mortem. --item-type distinguishes two kinds: action (an action item anchored to an active incident) and follow_up (a post-mortem follow-up, which must be bound to a post-mortem ID).

flashduty incident work-item-create <incident-id> [flags]        # Create an action item / follow-up
flashduty incident work-item-list [flags]                        # List work items
flashduty incident work-item-update <work-item-id> [flags]       # Update title/description/status/priority
flashduty incident work-item-complete <work-item-id> [flags]     # Mark complete
flashduty incident work-item-convert <work-item-id> [flags]      # Convert an action item into a follow-up
flashduty incident work-item-delete <work-item-id> [flags]       # Delete a work item
flashduty incident work-item-assignees-reset <work-item-id>      # Reset the assignee list
flashduty incident work-item-post-mortem-bind [flags]            # Bind converted follow-ups to a post-mortem

Key flags for work-item-create: --item-type (required, action or follow_up), --title (required, up to 512 characters), --idempotency-key (required idempotency key, up to 128 characters), --post-mortem-id (required for follow_up, forbidden for action), --assignee-ids (initial assignees). Mutating verbs (update/complete/convert/delete/assignees-reset) require --version (optimistic locking — it must match the stored version).

Post-mortem reports (post-mortem-*)

Post-mortem verbs live under the incident command group (there is no standalone post-mortem group):

flashduty incident post-mortem-init <incident-id> [<id2>...]        # Initialize a report from 1–10 incidents (--template-id required)
flashduty incident post-mortem-list [flags]                         # List reports (server defaults to published; pass --status drafting for drafts)
flashduty incident post-mortem-info <post-mortem-id>                # Get report detail
flashduty incident post-mortem-title-reset <post-mortem-id>         # Set the title
flashduty incident post-mortem-content-reset <post-mortem-id>       # Replace the Markdown body (--markdown-file)
flashduty incident post-mortem-basics-reset <post-mortem-id>        # Update start/close time, highest severity, responder metadata
flashduty incident post-mortem-follow-ups-reset <post-mortem-id>    # Set follow-ups (--follow-ups)
flashduty incident post-mortem-status-reset <post-mortem-id>        # Publish or revert to draft (--status drafting|published)
flashduty incident post-mortem-delete <post-mortem-id>              # Delete a report (irreversible)

Template verbs: post-mortem-template-list, post-mortem-template-info <template-id>, post-mortem-template-upsert (creates when --template-id is omitted; --team-id is required when creating), post-mortem-template-delete <template-id> (irreversible).

Comment types (comment-type-*)

flashduty incident comment-type-create [flags]                # Create (--name ≤40 chars, unique within the account; --color #RRGGBB)
flashduty incident comment-type-list                          # List all comment types
flashduty incident comment-type-update <comment-type-id>      # Update name/color
flashduty incident comment-type-delete <comment-type-id>      # Delete
flashduty incident comment-type-reorder <id> [<id2>...]       # Reorder — pass every comment type ID in the account, in the desired order

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
flashduty member info-reset [flags] # Update a member's profile
flashduty member invite [flags]     # Invite new members (up to 20 per call)

member list supports --query (free-text search by name or email), --role-id, --page, --limit, --orderby, --asc. member info-reset identifies the member by exactly one of --member-id, --member-name, --email, --phone, or --ref-id; the fields to change go into the required body via --data '{"updates":{...}}'. With --from api, an updated email or phone is marked verified directly when the account has member invites disabled. member invite takes the member list via --data '{"members":[...]}'. When the account has member invites disabled and --from api is set, members are created directly in the enabled state with email/phone marked verified — no invitation is sent.

team — Team management

flashduty team list [flags]                          # List teams with members
flashduty team info --team-id <id>                   # Get a single team's details
flashduty team upsert --team-name <name> [flags]     # Create or update a team (update when --team-id is set)
flashduty team delete --team-id <id>                 # Delete a team (irreversible)

team list supports --query (team name substring match), --page, --limit, --orderby (created_at/updated_at/team_name), --asc, --person-id (filter to teams the given member belongs to). team info accepts --ref-id, --team-name, or --team-id to identify the team (exactly one required). When several are provided, the precedence is --ref-id > --team-name > --team-id. team upsert creates or updates a team:

--team-name (required, 1–39 characters)
--team-id (set to update an existing team; omit to create)
--description (up to 500 characters)
--person-ids (member ID list; replaces the entire member list — run team info first to see current members before updating)
--emails (add existing members by email; addresses that match no existing member are silently ignored — no invitation is sent)
--phones (add existing members by phone number; non-matching numbers are silently ignored, and non-E.164 numbers are parsed with --country-code)
--country-code (default country code applied to --phones entries that are not in E.164 format)
--ref-id (external reference ID for HR system integration)

team upsert’s --emails / --phones only match and attach existing members — no invitation is ever sent. To invite new members into the organization, use flashduty member invite.

team delete accepts --team-id, --team-name, or --ref-id to identify the team. This action is permanent and cannot be undone.

channel — Channel queries

flashduty channel list [flags]   # List channels

Supports --name.

channel escalate-rule-list — Escalation rule queries

Escalation rule management has moved into the channel command group. Pass the channel ID as a positional argument:

flashduty channel escalate-rule-list <channel-id>   # List all escalation rules for a channel

Other escalation rule management commands under the channel group: escalate-rule-create, escalate-rule-update, escalate-rule-delete (all require --channel-id).

channel silence/inhibit/drop rules — Noise rule management

Channel-level noise rules are managed through the channel command group; see Noise Reduction for rule semantics and configuration. The three families — silence-rule-* (silence), inhibit-rule-* (inhibit), unsubscribe-rule-* (drop) — share the same shape, each with list/create/update/enable/disable/delete verbs:

flashduty channel silence-rule-list <channel-id>                    # List silence rules (channel-id is positional)
flashduty channel silence-rule-create <channel-id> [flags]          # Create (--rule-name required, 1–39 chars; time window and filters go via --data)
flashduty channel silence-rule-update --channel-id <id> --rule-id <id>   # Update
flashduty channel silence-rule-enable --channel-id <id> --rule-id <id>   # Enable
flashduty channel silence-rule-disable --channel-id <id> --rule-id <id>  # Disable
flashduty channel silence-rule-delete --channel-id <id> --rule-id <id>   # Delete

inhibit-rule-* and unsubscribe-rule-* work the same way; inhibit-rule-create requires --equals (the label keys pairing source and target alerts). Silence and inhibit rules accept --is-directly-discard to drop suppressed alerts instead of merging them. Note that channel-id is positional on *-rule-create and *-rule-list but a flag (--channel-id) on *-rule-update/delete/enable/disable; --rule-id is a MongoDB ObjectID string.

field — Custom field queries

flashduty field list [flags]     # List custom field definitions

Supports --name.

status-page — Status page management

flashduty status-page list                                             # List status pages
flashduty status-page change-active-list <page-id>                    # List active status page events
flashduty status-page change-create <page-id> [flags]                 # Create a status page event
flashduty status-page change-timeline-create [flags]                  # Append a timeline update

Migrate from Atlassian Statuspage

Migration jobs run asynchronously. Poll progress with migration-status after kicking off a job:

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

# 2. Check job status
flashduty status-page migration-status <job-id>

# 3. Migrate email subscribers
flashduty status-page 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 status-page migration-cancel <job-id>

Other available subcommands: change-delete, change-info, change-list, change-timeline-delete, change-timeline-update, change-update, component-upsert, component-delete, section-upsert, section-delete, info, subscriber-list, subscriber-import, subscriber-export, template-list, template-upsert, template-delete.

rum — RUM applications and session replay

Use these commands to manage RUM applications and export session replay data. The application commands cover detail, batch reads, listing, webhook testing, and create/update/delete operations.

flashduty rum application-info <application-id>            # Get one application's detail
flashduty rum application-infos <id1> [<id2>...]          # Batch get multiple applications
flashduty rum application-list [flags]                    # List accessible applications
flashduty rum application-webhook-test <application-id>   # Send a sample alert to a webhook URL
flashduty rum application-create <team-id> [flags]        # Create an application
flashduty rum application-update <application-id> [flags] # Update an application
flashduty rum application-delete <application-id>         # Delete an application

Common flags for application-list:

Flag	Description
`--query`	Search by application name
`--team-id`	Restrict results to one team
`--is-my-team`	Return only applications owned by the caller’s teams
`--orderby`	Sort field: `created_at` or `updated_at`
`--asc`	Sort ascending

Core fields for application-create / application-update:

Flag	Description
`--application-name`	Application name; required on create, 1-40 characters
`--type`	Application type: `browser`, `ios`, `android`, `react-native`, `flutter`, `kotlin-multiplatform`, `roku`, `unity`, `miniprogram`, `harmony`, `electron`
`--team-id`	Owning team ID (required on create)
`--is-private`	Restrict access to team members only
`--no-geo`	Disable geographic inference
`--no-ip`	Disable IP collection
`--data`	Add `alerting` and `tracing` objects when you need notification or trace-link configuration

application-webhook-test returns ok, status_code, and message, which makes it suitable for verifying that a RUM alert webhook really accepts a sample delivery from Flashduty.

Session replay

flashduty rum session-replay-metadata <session-id> # Get the application, device, session-boundary, and view metadata for a replayable session
flashduty rum session-replay-segments <session-id> # Read session replay segments

For session-replay-metadata, use --ts to supply the session-start Unix timestamp in milliseconds when you need to disambiguate a reused session ID from different time windows. Common session-replay-segments flags:

Flag	Description
`--limit`	Number of segments to return, from 1 to 99; default: 20.
`--search-after-ctx`	Pagination cursor from the previous page. In URL mode, read `search_after_ctx`; in streaming mode, read the `X-Search-After-Ctx` response header.
`--ts`	Without `--search-after-ctx`, begin at the most recent full-snapshot segment at or before this timestamp.
`--url-mode`	When `true`, return JSON containing presigned download URLs. By default it is `false` and streams segment bytes directly. URLs are valid for one hour.
`--view-id`	Return segments for one view only; omit it to page through the whole session.

Error ingestion rules (error-ingestion-rules-*)

Error ingestion rules filter or rewrite the error events an application reports:

flashduty rum error-ingestion-rules-create <application-id> [flags]       # Create (--rule-name required, 1–128 chars; filters go via --data)
flashduty rum error-ingestion-rules-list <application-id>                 # List rules
flashduty rum error-ingestion-rules-update [flags]                        # Update (--application-id, --rule-id required)
flashduty rum error-ingestion-rules-enable [flags]                        # Enable
flashduty rum error-ingestion-rules-disable [flags]                       # Disable
flashduty rum error-ingestion-rules-delete [flags]                        # Delete
flashduty rum error-ingestion-rules-history-list <application-id>         # View change history (--orderby updated_at|version)
flashduty rum error-ingestion-rules-history-revert <application-id> --version <v>  # Revert to a history version

--description is capped at 512 characters. create/list/history-list/history-revert take application-id as a positional argument; update/enable/disable/delete target rules via the --application-id and --rule-id flags.

Preset severity rules (issue-preset-severity-rules-*)

Preset severity rules assign a preset severity to errors matching a condition, used for issue grading:

flashduty rum issue-preset-severity-rules-create <application-id> [flags]  # Create (--rule-name required; --severity Critical|Warning|Info required)
flashduty rum issue-preset-severity-rules-list <application-id>            # List rules
flashduty rum issue-preset-severity-rules-update [flags]                   # Update
flashduty rum issue-preset-severity-rules-enable [flags]                   # Enable
flashduty rum issue-preset-severity-rules-disable [flags]                  # Disable
flashduty rum issue-preset-severity-rules-delete [flags]                   # Delete
flashduty rum issue-preset-severity-rules-reorder [flags]                  # Reorder priority (--drag-rule-id, --target-rule-id)
flashduty rum issue-preset-severity-rules-history-list <application-id>    # Change history
flashduty rum issue-preset-severity-rules-history-revert <application-id> --version <v>  # Revert

Resource info (resource-info)

flashduty rum resource-info [--no-cache]   # View the RUM plan version, quotas, and usage (--no-cache bypasses the short-lived cache)

oncall — On-call licenses

flashduty oncall license-list # List people with active On-call licenses in the current account

This read-only command returns each person’s ID, name, and license type: fixed is explicitly assigned, while temporary is active for the current temporary-license window.

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`
`--output-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

monit-agent — On-box host/database diagnostics

Run live diagnostics on a target host or data source through flashmonit agents, without needing a shell login on the target machine.

flashduty monit-agent catalog --target-locator <host>    # List available diagnostic tools for a target
flashduty monit-agent invoke  --target-locator <host> --data '<json>'  # Run up to 8 tools concurrently

Both subcommands require --target-locator (internal IP, hostname, or data-source name). --target-kind is optional (host, mysql, redis, etc.) and is inferred automatically when omitted. invoke accepts a --data JSON payload listing the tools to run, up to 8 concurrently:

flashduty monit-agent invoke --target-locator '10.0.0.1' \
  --data '{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]}'

For SQL parameters containing quotes or commas, pass --data - and supply the body via a stdin heredoc to avoid shell-quoting issues:

flashduty monit-agent invoke --target-locator 'db-host' --data - <<'FDUTY'
{"tools":[{"tool":"mysql.query","params":{"sql":"SELECT a, b FROM t WHERE s='RUNNING'","max_rows":50}}]}
FDUTY

monit-query — Monitoring datasource queries

Probe monitoring back-end datasources directly, bypassing the alert-rule layer. The data subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse); diagnose supports prometheus (metric trends), victorialogs, loki (log patterns); the deprecated rows supports prometheus, victorialogs, loki, mysql.

flashduty monit-query diagnose [flags]   # Pre-clustered RCA findings (log patterns or metric trends)
flashduty monit-query data [flags]       # Structured datasource query (recommended)
flashduty monit-query rows [flags]       # Raw datasource passthrough query (deprecated — use data)

Common flags for diagnose:

Flag	Description
`--ds-type`	Datasource type supported by the diagnose endpoint (required): `prometheus`, `victorialogs`, `loki`
`--ds-name`	Datasource name as configured in the console (required)
`--input-query`	Filter-only log query or matrix PromQL (required)
`--time-start`	Window start (default `15m`). Accepts a relative duration (`15m`, `1h`), `now`, a date/RFC3339 timestamp, or a unix epoch in seconds or milliseconds
`--time-end`	Window end (default `now`); same formats as `--time-start`; the window is capped at 6h
`--operation`	`log_patterns` (`loki` / `victorialogs`) or `metric_trends` (`prometheus`); inferred from `--ds-type` when omitted

Common flags for data:

Flag	Description
`--ds-type`	Datasource type (required): `prometheus`, `victorialogs`, `loki`, `mysql`, `sls`, `elasticsearch`, `postgres`, `oracle`, `clickhouse`
`--ds-name`	Datasource name as configured in the console (required)
`--expr`	Query expression (required)
`--delay-seconds`	Look-back offset in seconds for point-in-time queries (default `0`)
`--args KEY=VALUE`	Additional arguments, repeatable (values must be strings). In raw mode (`loki` / `victorialogs`), `<ds-type>.start` and `<ds-type>.end` accept a relative duration (`15m`), `now`, a date/RFC3339 timestamp, or unix seconds/milliseconds; the CLI normalizes them to the unix-seconds form the datasource requires

data returns a stable query_result.v1 structured result: format is always query_result.v1, and result.kind is one of frames (typed table/time-series frames), records (schema-flexible records, may contain nested JSON or null), or samples (instant samples with complete label sets) — results are no longer flattened into the legacy rows shape. rows requires --ds-type, --ds-name, and --expr (query expression). Use --args KEY=VALUE (repeatable) for parameterized queries. rows is deprecated — use monit-query data instead. In raw mode (loki / victorialogs), rows accepts time-window arguments --args <ds-type>.start=<t> and --args <ds-type>.end=<t> in the same formats as diagnose’s --time-start/--time-end (relative duration, now, date/RFC3339, unix seconds or milliseconds); the CLI normalizes them to the unix-seconds form the datasource requires.

monit — Alert-expression preview

If you want to validate a datasource expression before saving a rule, use preview-sync to execute a synchronous preview request and inspect the raw result.

flashduty monit preview-sync [flags]

Common flags:

Flag	Description
`--ds-name`	Datasource display name (required, must match the console configuration)
`--ds-type`	Datasource type (required), such as `prometheus`, `loki`, or `elasticsearch`
`--expr`	Query expression to preview (required)
`--delay-seconds`	Shift the query window backward by a few seconds to compensate for ingestion latency
`--data`	Add datasource-specific parameters such as `args`

monit servicemap — Service topology (Beta)

The monit servicemap-* command family accesses the ServiceMap capability; see Service Map for the UI workflow.

flashduty monit servicemap-fleet [flags]             # Browse fleet hosts (filter by --statuses/--agent-versions/--capture-modes/--edge-clusters)
flashduty monit servicemap-fleet-summary [flags]     # Fleet host summary
flashduty monit servicemap-status [flags]            # Check host collection status (--host-id/--host-ids, or --fleet to sample)
flashduty monit servicemap-summary --data '<json>'   # Get a topology summary for an anchor host
flashduty monit servicemap-topology --data '<json>' [flags]  # Query topology (--depth 1–3, default 1)

summary and topology take the anchor host via --data '{"anchor":{...}}'. Common topology flags: --depth (traversal depth, 1–3, default 1), --max-nodes (default 100, cap 500), --max-edges (default 200, cap 1000).

alert — Alert and alert-event queries

flashduty alert list [flags]        # List alerts (default: last 24h)
flashduty alert get <alert_id>      # Get full detail of one alert; detail is an alias
flashduty alert-event list [flags]  # List alert events (default: last 1h)

Common filter flags for both list commands: --severity (Critical,Warning,Info), --channel (comma-separated channel IDs), --integration (comma-separated integration IDs), --since/--until, --limit (max 100), --page. alert-event list also takes --integration-type, which filters by comma-separated plugin keys (e.g. AliCloud,Prometheus) — note these are plugin keys, not integration IDs; use --integration to filter by integration ID.

automation — AI SRE automation rules

The automation command group manages AI SRE automation rules — create, query, update, delete, run history, and triggering. See Automations for the console workflow.

flashduty automation create [flags]               # Create a rule
flashduty automation list [flags]                 # List rules visible to the caller
flashduty automation get <rule_id>                # Get one rule by ID
flashduty automation update <rule_id> [flags]     # Update mutable fields on a rule
flashduty automation delete <rule_id> [flags]     # Delete a rule (interactive confirmation; --force skips it)
flashduty automation runs <rule_id> [flags]       # List a rule's run history
flashduty automation templates [--locale zh-CN]   # List preset templates
flashduty automation fire <trigger_id>            # Fire one run through its HTTP POST trigger

Common create flags:

Flag	Notes
`--name`	Rule name (required)
`--team-id`	Scope team ID; `0` means personal scope (default). The scope is immutable after creation
`--schedule`	Schedule helper: `hourly`, `daily`, `weekly`, or `cron`; defaults to `daily` when omitted
`--at`	`HH:MM` local time (in the rule’s timezone); for `hourly` only the minute is used (default 0), for `daily`/`weekly` both hour and minute (default 09:00)
`--weekday`	Weekday for `weekly`: `sun`–`sat` or `0`–`7` (`0` and `7` both mean Sunday; defaults to Monday)
`--cron-expr`	Exact 5-field cron expression (interpreted in the rule’s timezone); overrides the `--schedule` helpers
`--disabled`	Create the rule disabled (enabled by default)
`--schedule-enabled`	Whether the schedule trigger is enabled (default `true`)
`--http-post-trigger`	Create and enable an HTTP POST trigger; when passed alone without any schedule flags, the CLI writes a placeholder cron and disables the schedule trigger
`--prompt` / `--prompt-file`	Task prompt, exactly one required; `--prompt-file` reads from a file (`-` for stdin)
`--environment-kind` / `--environment-id`	Runtime environment: `cloud` or `byoc` (`byoc` requires `--environment-id`); empty means automatic

update accepts --name, --prompt/--prompt-file, --schedule/--at/--weekday/--cron-expr, --enable/--disable, --enable-schedule/--disable-schedule, --enable-http-post-trigger/--disable-http-post-trigger, --rotate-http-post-token, and --environment-kind/--environment-id. The personal/team scope is immutable after creation, so update exposes no scope flag. runs supports --status (queued/running/retrying/succeeded/partial/failed/skipped/abandoned), --trigger-kind (schedule/debug/http_post), --since/--until, --page, and --limit. fire authenticates with the trigger’s token (--token, or the FLASHDUTY_AUTOMATION_TRIGGER_TOKEN environment variable); --text passes context for the run, and --data passes a full JSON request body (inline JSON or - to read stdin).

Timezone semantics: --at and --cron-expr are interpreted as local wall-clock time in the rule’s timezone, which defaults at creation to the caller’s member timezone, falling back to the account timezone when the member has none. Pass the user’s local time directly — do not convert it to UTC. Neither create nor update has a --timezone flag: to pin a different timezone at creation, use the generated command flashduty safari automation-rule-create --timezone; a created rule’s timezone cannot be changed via update.

Full command coverage

Beyond the curated commands above, the CLI now provides full coverage of the Flashduty OpenAPI through a spec-driven code generator. The current OpenAPI contains 337 API operations, and the CLI generates corresponding resource-organized commands for 336 of them (session-read-export is provided by the hand-written session export / safari session-export commands). In addition to the On-call domain (incident, incident-trigger-subscription, change, channel, field, status-page, template, and more), it also covers:

AI SRE (safari): a2a-agents, automations, knowledge, 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

Time-window parameters on generated commands (--start-time / --end-time) accept the same human-friendly formats as the curated commands: relative durations (7d, 24h — interpreted as “now minus duration”), +7d (“now plus duration”, i.e. a future time), now, dates and datetimes (such as 2026-05-01 or 2026-05-01 10:00:00), and unix timestamps in seconds. In addition, --since and --until are aliases for --start-time and --end-time respectively and can be used interchangeably; passing both spellings with different values is an error.

knowledge — AI SRE knowledge base

The safari knowledge-* command family manages AI SRE Knowledge Packs — versioned, account/team-scoped file trees (DUTY.md plus runbooks, FAQs, service catalogs, and similar files) staged into every AI SRE sandbox at session start. See Manage Knowledge for the full feature model (DUTY.md structure, @references, account/team scope, file constraints).

flashduty safari knowledge-get                                  # Get the account knowledge pack (with its file list)
flashduty safari knowledge-pack-list [flags]                    # List knowledge packs
flashduty safari knowledge-pack-ensure --scope <account|team> [--scope-id <team-id>]  # Ensure a knowledge pack exists (create if missing)
flashduty safari knowledge-pack-update <pack-id> [--scope ...]  # Change a pack's scope
flashduty safari knowledge-pack-delete <pack-id>                # Delete a knowledge pack (irreversible)
flashduty safari knowledge-file-list [--pack-id <id>]           # List files within a pack
flashduty safari knowledge-file-get --rel-path <path>           # Read a single knowledge file (content is Base64-encoded)
flashduty safari knowledge-file-put --rel-path <path> --content-b64 <base64>  # Upload or overwrite a knowledge file
flashduty safari knowledge-file-delete --rel-path <path> [--force]  # Delete a knowledge file

Common flags:

Flag	Description
`--pack-id`	Knowledge pack ID; defaults to the caller’s account-scope pack when omitted
`--rel-path`	File path relative to the pack root (required; subdirectories allowed, e.g. `runbooks/api-5xx.md`)
`--scope`	Pack scope: `account` or `team` (required for `knowledge-pack-ensure`)
`--scope-id`	Team ID; required for `team` scope, ignored for `account` scope
`--force`	On file delete, skip the “still referenced” check; referrers are then returned as warnings

knowledge-file-put requires --content-b64 to be the Base64 encoding of valid UTF-8 text; --content-type is inferred from the file extension when omitted. knowledge-file-delete refuses to remove a file still referenced by other pack files unless --force is passed, in which case the referrers are returned as warnings.

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 whoami         # Show the current authenticated identity (account ID, email, role)
flashduty update         # Update to the latest version
flashduty update --check # Check for updates without installing
flashduty completion     # Generate shell completions (bash/zsh/fish/powershell)

flashduty update downloads and runs the platform installer, replacing the current binary with the latest release. --check only prints the available version without modifying any local files. After any non-update command runs in a terminal, if a newer version is available the CLI automatically emits an update notice banner to stderr.

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. Except for the commands with default compact fields listed below, it returns the command’s full response data; table-column truncation does not apply to JSON. Ideal for scripts and CI/CD pipelines.

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

TOON (Token-Oriented Object Notation) drops the per-row field names that JSON repeats for homogeneous arrays, cutting token usage substantially on list output and making it well suited to AI agents. Commands with default compact fields listed below emit their field projections and are size-bounded.

flashduty incident list --output-format toon

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

Field projections for structured output

The following commands support --fields with json or toon output. Supply comma-separated top-level response fields; an unknown field fails immediately, and table output ignores this flag.

Command	Structured output when `--fields` is omitted	Limit
`flashduty incident list`	`incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `channel_id`	16 KiB
`flashduty incident similar <id>`	`incident_id`, `title`, `incident_severity`, `progress`, `start_time`, `close_time`, `ack_time`, `alert_cnt`, `root_cause`, `score`	16 KiB
`flashduty incident detail <id>`	Returns full detail when `--fields` is omitted; otherwise returns only the selected fields	8 KiB for projections only
`flashduty alert-event list`	`event_id`, `alert_id`, `event_severity`, `event_status`, `event_time`, `title`	16 KiB

For example, export only an incident ID, title, and progress:

flashduty incident list --json --fields incident_id,title,progress

When a list projection (incident list, incident similar, alert-event list) exceeds its limit, the CLI keeps the selected field names, shortens long strings, and marks them with .... If non-string fields alone exceed the limit, the command asks you to reduce the fields or result count. incident detail behaves differently when its projection overflows: the detail is a single object, and a truncated value is indistinguishable from a genuinely short one, so silently shortening it would hand you wrong data. A projection over 8 KiB therefore fails the command outright, and the error names the largest fields (up to 3, with their byte sizes). Reduce the fields in --fields, or omit --fields entirely to get the full detail, which is not subject to the projection limit. When --fields is omitted and the default compact projection is used, the CLI prints a one-line note to stderr stating which fields the projection uses and that --fields can select others. The note goes only to stderr and never touches stdout, so piping into jq or similar tools is unaffected.

Agent skills

Flashduty CLI ships with a single agent skill named flashduty that teaches AI coding agents — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and 40+ others — how to operate Flashduty from your terminal. Install it to every detected agent on your machine in one shot:

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

The skill uses a router-plus-reference-card structure: SKILL.md carries the shared conventions (authentication, global flags, safety rules) and indexes per-domain reference cards — incidents, alerts, changes, on-call and schedules, channels and escalations, status pages, insights, monitors, RUM and sourcemaps, automations, notification templates, members and teams, and more. Before running a task, the agent reads the card for that domain to get every command, flag, and workflow for it — no --help trial-and-error.

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.

​Overview

​Installation

​Installer options

​Authentication

​Log in

​Credential resolution order

​Config file

​Config commands

​Global flags

​Command catalog

​incident — Incident lifecycle

​Work items and follow-ups (work-item-*)

​Post-mortem reports (post-mortem-*)

​Comment types (comment-type-*)

​change — Change records

​member — Member queries

​team — Team management

​channel — Channel queries

​channel escalate-rule-list — Escalation rule queries

​channel silence/inhibit/drop rules — Noise rule management

​field — Custom field queries

​status-page — Status page management

​Migrate from Atlassian Statuspage

​rum — RUM applications and session replay

​Session replay

​Error ingestion rules (error-ingestion-rules-*)

​Preset severity rules (issue-preset-severity-rules-*)

​Resource info (resource-info)

​oncall — On-call licenses

​template — Notification templates

​session — AI SRE sessions

​monit-agent — On-box host/database diagnostics

​monit-query — Monitoring datasource queries

​monit — Alert-expression preview

​monit servicemap — Service topology (Beta)

​alert — Alert and alert-event queries

​automation — AI SRE automation rules

​Full command coverage

​knowledge — AI SRE knowledge base

​Utility commands

​Output formats

​Field projections for structured output

​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

Work items and follow-ups (work-item-*)

Post-mortem reports (post-mortem-*)

Comment types (comment-type-*)

change — Change records

member — Member queries

team — Team management

channel — Channel queries

channel escalate-rule-list — Escalation rule queries

channel silence/inhibit/drop rules — Noise rule management

field — Custom field queries

status-page — Status page management

Migrate from Atlassian Statuspage

rum — RUM applications and session replay

Session replay

Error ingestion rules (error-ingestion-rules-*)

Preset severity rules (issue-preset-severity-rules-*)

Resource info (resource-info)

oncall — On-call licenses

template — Notification templates

session — AI SRE sessions

monit-agent — On-box host/database diagnostics

monit-query — Monitoring datasource queries

monit — Alert-expression preview

monit servicemap — Service topology (Beta)

alert — Alert and alert-event queries

automation — AI SRE automation rules

Full command coverage

knowledge — AI SRE knowledge base

Utility commands

Output formats

Field projections for structured output

Agent skills

Common workflows