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. Release notes and downloads are on GitHub Releases.
Installation
- macOS / Linux
- Windows (PowerShell)
- Manual download
flashduty already on your PATH by default, so an upgrade replaces that copy in place; when there is no flashduty on PATH, it installs to /usr/local/bin. Override the directory with the FLASHDUTY_INSTALL_DIR environment variable.Installer options
A copy installed under another command name uses that name in help output, error messages, and shell completion scripts;
flashduty update replaces the running binary in place, under its own name and directory, instead of installing a default-named copy elsewhere.
After installing, the script re-checks PATH: if the flashduty your shell actually runs is not the copy it just installed (an older copy earlier on PATH shadows it), it tells you to remove that copy or move the new directory ahead of it. When the current process is managed by flashduty-runner (FLASHDUTY_MANAGED_BY_RUNNER=1), the script refuses to run and tells you to upgrade the runner instead — the runner ships a CLI copy it was built and verified against, and replacing it in place desyncs the two.
Authentication
Log in
Credential resolution order
The CLI resolves credentials in the following order (highest priority first):--app-keycommand-line flag (hidden, for scripting)FLASHDUTY_APP_KEYenvironment variable- Config file
~/.flashduty/config.yaml(written byflashduty login)
Environment variables
The CLI reads the following environment variables at runtime (variables understood by the installer scripts are listed above under “Installer options”):Config file
Stored at~/.flashduty/config.yaml with 0600 permissions:
Config commands
Global flags
These flags are registered on the root command; every subcommand accepts them except--version:
Command catalog
incident — Incident lifecycle
incident list:
Time format examples:
5m, 1h, 24h, 168h, 2026-04-01, 2026-04-01 10:00:00, 1712000000.
incident feed <id> reads an incident’s feed (timeline entries) page by page. --asc lists the oldest entries first (the default is newest first). --types filters by comma-separated entry types, for example i_comm,i_assign; each entry’s type field gives its actual type. --limit (max 100) and --page paginate the result.
incident alerts <id> lists the alerts attached to that incident; --limit defaults to 10 and --page starts at 1.
Create, update, and merge
incident create requires --title (3–200 characters) and --severity, and prompts for missing values in a terminal. There are three ways to assign people, which can be combined: --assign (member IDs), --assign-emails (member emails, comma-separated; emails that match no member are ignored), and --escalate-rule-id with --escalate-layer (assign the people at that zero-based layer of the escalation rule; --escalate-layer requires --escalate-rule-id).
incident create and incident update both accept a repeatable --field key=value to set custom fields. Values are converted by the field type: checkbox takes true / false; multi-select takes comma-separated options or a JSON array (such as a,b or ["a","b"]); single-select and text take a string.
incident merge <target-id> merges the incidents in --source (comma-separated source incident IDs, at most 100) into the target. By default, the source incidents are closed and kept, and a merge entry is added to the target timeline. With --remove-source-incidents, they’re deleted and no longer appear in the incident list. --title renames the target, and --comment-file reads an optional merge comment from a file (- reads stdin).
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).
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, a legacy alias). Mutating verbs (update/complete/convert/delete/assignees-reset) require --version (optimistic locking — it must match the stored version).
A work item’s status accepts only four values — open, in_progress, done, cancelled: work-item-create --status defaults to open when omitted or blank, work-item-update --status can only move it to one of those four, work-item-complete --target-status accepts done alone (any other value is rejected), and work-item-convert --target-status takes one of the four.
A work item’s assignees can be members or the account’s AI SRE:
work-item-createandwork-item-assignees-resetaccept anassigneesfield (each entry shaped{type, id?}, wheretypeispersonorai_sre; anai_sreentry carries noid, and at most 20 entries are allowed), which can only be passed as JSON through--data.--assignee-idsis the equivalent legacy alias (an all-personlist); the two are mutually exclusive and sending both returns an error.work-item-listgains--assignee-type person|ai_sre:ai_srereturns items assigned to AI SRE (an AI caller uses it to list its own tasks) and needs no--assignee-id, which is ignored in that case;personcombined with--assignee-idreturns only that member’s items. Omitting the flag with a positive--assignee-idfilters byperson.- In a work item response,
assignee_idsholds only person assignees (not AI SRE), andassigneesholds the full list. Items executed by AI SRE also returnagent_session_idandagent_session_venue(weborim). Both are omitted when no session is recorded.
Post-mortem reports (post-mortem-*)
Post-mortem verbs live under theincident command group (there is no standalone post-mortem group):
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-*)
--comment-type-id: flashduty incident comment <id> [<id2>...] --comment-file <path> --comment-type-id <comment-type-id>. The comment type ID comes from flashduty incident comment-type-list; omit the flag to write the comment without a type.
change — Change records
--channel, --integration (reporting integration IDs), --query (free-text/regex search), --filters (structured filters as a JSON array), --include-events (include the underlying change events), --since, --until (window must be under 31 days), --orderby (start_time or last_time), --asc, --limit, --page.
member — Member queries
member list supports --query (free-text search by name or email), --role-id, --member-id (return only the member with this 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 through --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 through --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
team list supports --name (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 — runteam infofirst 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--phonesentries that are not in E.164 format)--ref-id(external reference ID for HR system integration)--reset-if-name-exist(when--team-idis empty and a team with the same name exists, update it in place instead of returning a name conflict)
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 --id, --name, or --ref-id to identify the team and asks for confirmation in an interactive terminal (--force skips it). This action is permanent and cannot be undone.
channel — Channel queries
--name is a server-side, case-insensitive substring match over the channel name and description; use --channel-name for an exact name match. Other filters: --channel-ids, --team-ids, --is-my-managed, --is-my-starred, --is-my-team, --is-brief (only ID, name, description, and status, no pagination), --orderby, --asc, --limit, --page.
channel escalate-rule-list — Escalation rule queries
Escalation rule queries belong to thechannel command group. Pass the channel ID as a positional argument:
channel group: escalate-rule-create, escalate-rule-update, escalate-rule-delete, escalate-rule-reorder (all require --channel-id).
channel silence/inhibit/drop rules — Noise rule management
Channel-level noise rules are managed through thechannel 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:
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
--name (filter by field name), --query (case-insensitive regex over the field name), --creator-id, --orderby, --asc.
status-page — Status page management
Event drafts (draft-create)
draft-create stores a status page event draft (incident or maintenance) so a human can review and publish it from the console — the draft itself is never published publicly:
--source: opaque marker of the drafting origin (for example,my-script), up to 64 characters.- The
draftobject in--data(required, stored verbatim, up to 64 KB serialized). Required fields:page_id,type(incidentormaintenance),name,message; optionalchange_id(append an update to an existing event when > 0),status,affected_components, andstart_time/end_time(Unix epoch seconds, new maintenance only). - The response returns
draft_id(matchingdraft_[A-Za-z0-9]{22}) andcreated_at; the console review link carriesdraft_id.
Migrate from Atlassian Statuspage
Migration jobs run asynchronously. Poll progress withmigration-status after kicking off a job:
draft-create, 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.application-list:
Core fields for
application-create / application-update:
repositories inside --data links the application to the source code repositories that build it: an ordered array whose first entry is the primary repository, at most 10 entries, each entry a repo (GitHub repository in owner/name form, required) plus an optional subdir (the directory holding the application inside the repository, relative to the repository root — . is the repository root, and an empty value is saved as .). On create, the field sets the links. On update, it’s presence-based: passing it replaces the whole list, an empty array clears every link, and omitting it leaves them unchanged. application-info, application-infos, and application-list all echo the field back. Linking grants no access by itself: AI sessions can only read repositories granted to the account’s GitHub App installations (see Apps). This field is currently available through the API and CLI only; the console’s application management page does not expose repository links.
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.Remote configuration (application-remote-config-*)
Remote configuration holds per-application collection and privacy parameters; once published, an SDK picks it up on its next new session. For what each setting means and how publishing and activation work in the console, see Application Management · Remote Configuration:config object with enabled, activation, default, rules, custom, and refresh_on_foreground) goes in through --data; --data may also carry the whole request body, and positional arguments and typed flags override fields of the same name in it.
Both a publish and a revert allocate a new version number (a revert never reuses the old one). A change applies to new sessions. With
activation set to next_session (the default), running sessions are untouched. With immediate, a client ends its current session as soon as the change arrives, and a new session starts under the new configuration. Publishing enabled: false turns delivery off, and clients fall back to their SDK initialization settings.
Session replay
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:
Error ingestion rules (error-ingestion-rules-*)
Error ingestion rules filter or rewrite the error events an application reports:--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 through 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:Resource info (resource-info)
oncall — On-call licenses
fixed is explicitly assigned, while temporary is active for the current temporary-license window.
calendar — Service calendars
A service calendar is what escalation rules and silence rules use to tell working days from rest days; the console-side configuration and layer precedence are described in Service Calendar. The group is generated from the OpenAPI (see “Full command coverage” below):<cal-id> (shaped cal.<uuid>) is positional and comes from the cal_id of the items[] rows returned by calendar list; list returns account-created calendars only, so pass --kind region.official.holiday for public-holiday calendars (they are filtered by the caller’s locale unless you add --no-locale).
--help and the responses themselves reveal:
event-deleteboth deletes a single event and clears a date range. Pass--event-idto delete one event, or--start-atand--end-at(bothYYYY-MM-DD;end_atis exclusive and must be later thanstart_at) to clear every event the calendar itself holds over[start_at, end_at). The cleared days fall back to the linked holiday calendars and the weekly workdays — the same effect as clicking Reset to default on those dates in the console.event-upserttrims the calendar’s other own events off the same days: an event fully inside the range is deleted, one partly inside is shortened, and one spanning the range is split in two, so the latest write decides those days (--summaryis optional).- The
event-listresponse carriesdaysbeside theitemsrow array: keyed byYYYY-MM-DD, it gives every day in the requested scope itsis_off, theevent_idthat decided it, and thelayerthat decided it —custom(the calendar’s own events) beatsholiday(a linked holiday calendar), which beatsweekly(the weekly workdays); inside one layer a working-day event beats a rest day; a missinglayermeans no event covers that day, which counts as a working day. Readdaysto tell whether a day is a rest day; do not infer it fromitems, since one day can hold events from several layers.
template — Notification templates
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.
session list:
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 to stdout as newline-delimited JSON (NDJSON). The first line is always a session_meta envelope. Each later line is one event: user_message, llm_call, tool_call, subagent_dispatch, final_answer, agent_text, or error. Exports can be large, so redirect to a file instead of printing to the terminal:
safari send / safari watch — Talk to AI SRE from a terminal
flashduty safari send puts one message into an AI SRE session, and flashduty safari watch reads the agent’s answers back line by line. Together they run a whole investigation from a terminal or a script; the session is the same one the console shows — see Console chat.
send takes its text from exactly one of three sources: the positional argument, --message-file <path> (- means standard input), or standard input (read when neither of the other two is given and standard input is not a terminal). Passing both the positional argument and --message-file is an error. The body is capped at 32000 characters (counted as Unicode characters); over that the command fails and points you to --file for longer content, and giving neither text nor an attachment also fails.
On success stdout is one JSON receipt with
session_id, invocation_id, root_invocation_id, and delivery_mode; feed root_invocation_id to safari watch --root-invocation-id. The message goes out on the CLI channel with delivery_mode set to reply_only: the agent answers only through its reply tool, and you read those answers with safari watch. If the server does not grant that channel the command fails outright, naming the session_id and invocation_id — the message is already queued, but its answers will not appear in safari watch, and the command does not fall back to another delivery mode.
With --session-id, the command reads the session state first: if that session still has a turn running, the message is taken into that turn at its next step and answered there instead of waiting for a turn of its own; an idle session runs it as an ordinary turn.
With --file and no --session-id, the command creates the session first and then uploads.
safari watch writes events one per line to stdout: one compact JSON object each, with diagnostics on stderr and nothing else on stdout.
The agent’s answers are printed: messages it sends through its reply tool, and the final answer of a turn that does not use it. Tool calls, thinking, and other assistant text are its private working content and never appear. The watch follows the whole session, so the answers to other people’s messages in that session, and the answer of the turn that took this message in, are printed too.
After a disconnect the stream resumes from the last event received, so no message is printed twice. Re-arming a watch with
--since alone delivers the frame at exactly that millisecond again; to continue from your last line, pass its created_at as --since and its event_id as --since-event-id.
After 8 retries with no event at all the command gives up, exiting non-zero with the last error.
The command exits 0 once the watched request has settled (in a turn of its own, or into a running turn) and a settle that is not steered then leaves no background task and no running turn; a settled request that still lists background tasks keeps the watch open for the rounds those tasks post later. Unrecoverable errors (a 4xx other than 408 or rate limiting, and a failed execution environment) exit non-zero and also leave one {"type":"error",…} line on stdout, which for an environment failure is the failure event itself.
monit-query — Unified datasource tool invocation
monit-query executes a single named tool against a configured datasource — the unified entry for both query tools (<type>.query, covering prometheus, mysql, postgres, oracle, clickhouse, elasticsearch, loki, victorialogs, sls, tencent_cls) and diagnostic tools (for example, mysql.overview, redis_node.slowlog), bypassing the alert-rule layer. Get the datasource ID from the id field of monit datasource-list:
Query tools require every online Edge in the cluster to be v0.68.0 or later, and diagnostic tools require v0.71.0 or later. If the versions don’t match, the command fails with one of these error codes:
edge_upgrade_required (Edge too old), mixed_edge_versions (mixed Edge versions in the cluster), edge_version_unknown (an Edge version in the cluster can’t be identified), no_active_edge (no online Edge available). Upgrade Edge first; do not rotate Edge and retry.
By default a query result prints as a bounded plain-text digest (around 8 KB; diagnostic tool results are not digested): time series ordered by maximum with per-series min/max and their timestamps, average, first/last and a 12-bucket shape (each bucket with its start time); instant samples sorted by value; rows for tables; entry counts, constant fields, value counts for short low-cardinality fields and each entry’s varying fields for logs (message first). The first line states the resolved window, every cut states its counts and timestamps, and an empty result says so in one line.
Use --output-format json or toon for the complete result — every point, row, or entry. Those formats keep stdout to the result alone and note the window on stderr instead. The digest’s last line gives the jq path to that kind’s data in the JSON form (for example, .data.result.entries[] | .timestamp_ns, .fields["<name>"]), so you can project it directly without reading the whole result first.
The complete result of a query tool is a explore_result.v1 structure. format is always explore_result.v1. result.kind is samples (instant samples with complete label sets), frames (typed table/time-series frames), or logs (raw logs with applied_limit and has_more). For the diagnostic tool response shape, see monit datasource-tools-invoke below.
monit datasource-tools-invoke — Datasource diagnostics
monit datasource-tools-invoke executes one deterministic read-only tool against a configured datasource. It is equivalent to the monit-query command above, which is the recommended path. Get the datasource ID from the id field of monit datasource-list:
Semantics and limits:
- No tool catalog, no auto-replay, no fallback: one call runs exactly one named tool; fill parameters according to the datasource tool’s contract rather than guessing from the command list. Alongside diagnostic tools, the entry also supports
<type>.queryquery tools (prometheus,mysql,postgres,oracle,clickhouse,elasticsearch,loki,victorialogs,sls,tencent_cls). - Request body limit 128 KiB; complete success response limit 10 MiB; tool timeout at most 25 seconds.
- The datasource must have
enabled=true;alerting_enabled=falsedoes not block diagnostics. - Response:
data(tool-specific JSON evidence, preserved without conversion, never null),tool,datasource_id, optionalsummary, and atruncatedobject (withreason; its presence indicates truncation).
tool_not_supported (tool not supported), act as described above; on invalid_request, fix the parameters; on source_too_large or result_too_large, narrow the request.
monit — Datasources, dashboards, and rule groups
To validate a datasource expression before saving a rule, run it directly withmonit-query <datasource-id> --tool '<type>.query' (see above).
Datasource management (datasource-*)
Themonit datasource-* command family manages monitoring datasources (provided by the OpenAPI-generated commands):
datasource-create / datasource-update:
enabled and alerting_enabled are independent: alert evaluation requires both enabled=true and an alerting-capable type; alerting_enabled=false does not block non-alerting queries or tools, and monit datasource-list always reports alerting_enabled=false for diagnostic-only types.
Diagnostic-type payloads and secret handling:
redis_node:database(Redis database number, default 0),username/password,timeout_ms(default 3000, range 1000–10000).redis_sentinel:username/password,timeout_ms(default 3000).mongodb_mongod/mongodb_mongos:auth_source(authentication database, defaults toadmin; username and password must be configured together),username/password,timeout_ms(default 3000), TLS fields; client certificates are unsupported.kafka:sasl_mechanism(nonedefault /plain/scram-sha-256/scram-sha-512, the latter three require username and password),username/password,timeout_ms(default 5000), TLS fields (tls_min_versiondefaults to 1.2, max 1.3).- Passwords and
kafka.tls_keysupport${env:NAME}references (resolved on the edge); literal values are omitted from responses, only${env:...}references are echoed. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear.
Dashboards and rule folders (dashboard-* / folder-*)
Themonit dashboard-* family manages monitor dashboards (provided by generated OpenAPI commands). A dashboard is a dashboard.v1 document: pass the definition in --data when creating or updating. update, delete, move, and restore all require --expected-revision — if the revision you send is not the current one, the call is rejected with DashboardRevisionConflict, so re-read and submit again.
monit folder-* commands manage the folders themselves. folder-health returns a {items:[...]} paged envelope in which each entry carries only folder_id and has_issue (has_issue marks a folder whose visible descendants include active alerts or rule runtime issues), and folder-list returns a top-level array — read both with --json | jq. folder-create and folder-update return the updated folder object; folder-move and folder-delete return no folder object. A folder name may not contain ., /, or ,. folder-move requires dest-parent-id even when moving to the root (0), and folder-delete accepts only an empty folder — child folders, rules, or dashboards inside it make the call fail, so empty it yourself first.
Panel runtime and variable resolution take their time window and variable selections as JSON objects in --data (time uses millisecond from_ms / to_ms timestamps). dashboard-panel-preview and dashboard-runtime-variables-preview need a context: kind: existing with a dashboard_id targets a stored dashboard, kind: new with a folder_id targets a folder that does not hold one yet.
dashboard-runtime-queries-resolve takes two further flags that shape the result: --max-data-points (int, 2–5000; both the downsampling target and what decides the step the built-in time variables render with — omit it or send null for the server default of 100) and --preserve-builtin-variables (bool, off by default): when set, the built-in time variables stay verbatim in the resolved expressions so a caller with its own execution window can render them, while user variables are still resolved. The sibling commands dashboard-panel-run and dashboard-panel-preview already carried --max-data-points, likewise a 2–5000 downsampling target.
prometheus-api-v1-label-{label_name}-values — Query Prometheus label values
Lists every value of a label on a Prometheus-compatible data source. The command is named monit prometheus-api-v1-label-{label_name}-values (visible under flashduty monit --help); use it as written here:
The response body is the datasource’s native Prometheus payload, not the Flashduty
{request_id, error, data} envelope: on success it is {"status":"success","data":["api","db","worker"]}. If the datasource rejects a query, for example because of an unknown label name, the command exits non-zero. The error text is exactly what the datasource (or the Monitors proxy) returned. A Prometheus error looks like {"status":"error","errorType":"bad_data","error":"unknown label name"} and is unrelated to Flashduty’s error codes.
This command only reads the value set of one label; to fetch time series from an expression or run richer PromQL queries, use
monit-query <datasource-id> --tool 'prometheus.query' as described above.alert — Alert and alert-event queries
list commands: --severity (Critical,Warning,Info), --channel (comma-separated channel IDs), --integration (comma-separated integration IDs), --since/--until, --limit (max 100), --page. The --since/--until window must span under 31 days, as on incident list and change list. alert-event list also takes --integration-type, which filters by comma-separated plugin keys (for example, AliCloud,Prometheus) — note these are plugin keys, not integration IDs; use --integration to filter by integration ID.
alert list also takes these flags:
--alert-ids: comma-separated alert IDs.--alert-keys: comma-separated alert deduplication keys.--asc: sort oldest first by start time (the default is newest first).--by-updated-at: apply--since/--untilto the last-updated time instead of the start time.alert-event listalso supports--asc(oldest first; newest first by default), but has no--by-updated-atcounterpart.
alert list also filters by state through --active (active alerts only) and --recovered (recovered alerts only). They are mutually exclusive — passing both is an error — and passing neither applies no state filter. Active alerts can be older than a day, so with --active and no --since the window widens to 30 days by default (the window actually sent is reported by the stderr note).
alert events <alert_id> lists the raw events that make up one alert: leave --limit unset to take the server default of 20 (max 100), and --page starts at 1. It reads events for a single alert; for a time-window query across alerts use alert-event list.
automation — AI SRE automation rules
Theautomation command group manages AI SRE automation rules — create, query, update, delete, run history, and triggering. See Automations for the console workflow.
create flags:
When you create a rule from an IM conversation, omitting
--run-in lets the server bind the rule to that conversation and inherit its scope; you neither need to nor should pass a chat, platform, integration, or session ID — the server resolves and authorizes the current conversation. Once bound to a conversation, every ordinary run starts a fresh execution session and, where the IM integration creates threads, a fresh IM thread, and it stays on the conversation and immutable scope captured at creation rather than reusing an old session or thread; a retry of the same run reuses that run’s execution identity. If the bound conversation’s scope no longer matches the rule when it runs, the run is skipped — the rule is never moved or run in another conversation. War-room Automations keep their existing behavior. Because each run starts from a fresh context, write the prompt so it carries the chat context it needs (the service, the team, the delivery target) and do not refer to “above” or to an earlier session. Like the scope, the execution destination is immutable after creation.
The war room creation trigger starts a run whenever a war room (IM group chat) is created in one of the matching channels. That run’s session lives in the war room’s group chat, not in the console — --run-in does not apply to it, and it uses the execution environment already chosen in that group chat, so the rule’s own environment does not affect it. Field semantics and run behaviour: Automations · War room created.
update accepts --name, --prompt/--prompt-file, --schedule/--at/--weekday/--cron-expr/--timezone, --enable/--disable, --enable-schedule/--disable-schedule, --enable-http-post-trigger/--disable-http-post-trigger, --rotate-http-post-token, --enable-war-room-trigger/--disable-war-room-trigger, --war-room-channel-ids/--war-room-severities, and --environment-kind/--environment-id. --enable-war-room-trigger and --disable-war-room-trigger are mutually exclusive and error if both are passed; --war-room-channel-ids/--war-room-severities replace the trigger’s filters wholesale when passed, and the server requires both lists when update first creates the war room trigger. The personal/team scope and the execution destination (--run-in) are both immutable after creation, so update exposes neither. update’s --cron-expr carries the same constraint as create: the minute must be a fixed 0–59 integer, so the fastest schedule is hourly, and minute wildcards, ranges, lists, and steps are unsupported.
runs supports --status (queued/running/retrying/succeeded/partial/failed/skipped/abandoned), --trigger-kind (server-side values schedule/debug/manual/http_post/oncall_incident/war_room_created, where war_room_created is a run triggered by a war room being created), --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).
insight — Insight queries
Theinsight command family queries aggregated incident metrics over a time window (response times, notification counts, and so on):
insight incidents:
In
json/toon mode every record is printed in full, not clipped. To see only some fields, project with --fields (for example, --fields incident_id,title,severity); see “Field projections for structured output” under “Output formats” below.
insight top-alerts: --label is required (check or resource), --since/--until as above, --limit defaults to 10 (top-K), returning the alert count and event count per label value.
insight incident-export: writes the filtered incident list as a CSV of header row plus data rows (redirect to a file; --start-time/--end-time take Unix seconds). The export endpoint returns a one-shot CSV with a server-side row cap. After writing, the command compares the CSV row count with the incident-list total for the same filter. On a shortfall, the CSV is still written, a rows=N line goes to stderr, and the command exits non-zero with the written and total counts. Narrow the time window and retry.
Full command coverage
Beyond the curated commands above, the CLI covers all Flashduty Open APIs through a spec-driven code generator, organized into top-level command groups by resource. Runflashduty <group> --help to browse them. session export, safari send, safari watch, enrichment mapping-data-upload, safari skill-upload, and monit prometheus-api-v1-label-{label_name}-values (see “Query Prometheus label values” below) are hand-written. 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, artifacts, automations, knowledge, mcp-servers, sessions, skills, and more, plus the hand-writtensendandwatch(see “safari send / safari watch — Talk to AI SRE from a terminal” above) - 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), integration (create, read, update, delete and key-rotation for alert- and change-source integrations; secret masking and update rules in “integration — integrations and secrets” below),
channel integration-*(create, read, update, delete and key-rotation for channel-owned integrations, in “channel integration — dedicated integrations” below), webhook (integrations)
resource-action naming form (for example, flashduty safari a2a-agent-get, flashduty safari session-list); Every public API operation is reachable as flashduty <group> <verb>, with the name derived from its API path: request fields become typed flags, and --data accepts the full JSON request body (typed flags override fields with the same name). This page does not list them all; explore them level by level with flashduty <resource> --help:
--data carries a field the installed CLI version’s SDK has no field for, that field is not sent: once the request body is bound, the CLI prints warning: --data fields not sent, unknown to this CLI version: <field paths> on stderr (paths are dotted, array elements end in [], for example labels.k.note or targets[].purpose; several are comma-separated). The call itself still succeeds and stdout is unaffected — the warning means the fields you sent are newer than the installed CLI, so a script that depends on them taking effect should upgrade the CLI first.
Time-window flags on generated commands (--start-time / --end-time) accept the same formats as the curated commands:
- Relative durations such as
7dor24h, meaning “now minus duration”. +7d, meaning “now plus duration” (a future time).now.- Dates and datetimes, such as
2026-05-01or2026-05-01 10:00:00. - Unix timestamps in seconds. In addition,
--sinceand--untilare aliases for--start-timeand--end-timerespectively and can be used interchangeably; passing both spellings with different values is an error.
knowledge — AI SRE knowledge
Thesafari knowledge-* command family manages AI SRE Knowledge — 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).
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.
artifacts — AI SRE artifact gallery
Thesafari artifact-* command family manages artifacts produced by AI SRE sessions — publishing to the gallery, sharing, and signed downloads. See Artifacts for the console workflow:
public_urlis a console/share/artifact/<artifact-id>page served entirely from the CDN; it exists only while sharing is on, and anyone with the link can view the content without logging in.- The public snapshot is built from the artifact’s current
file_id. Ifshare_enabled=trueandshare_file_iddiffers fromfile_id, the snapshot is stale. Callartifact-gallery-share-syncto refresh it before you link to it externally. - The
artifact-signtoken is bound to the calling account and person and is valid for 5 minutes (responseexpires_in);download_url/preview_urlare relative paths (/safari/artifact/stream?...) — prepend the API base (https://api.flashcat.cloud). - An artifact’s initial scope inherits from its source session (personal-session artifacts belong to the creator; team-bound session artifacts belong to the team);
can_edittells whether the caller may rename/transfer/delete/share it (the creator, any member of the owning team, or a manager of the source session).
integration — integrations and secrets
Theintegration command family manages account-level public integrations — alert sources, change sources, IM bots and custom webhooks — with 9 subcommands: list, info <integration-id>, type-list, create, update <integration-id>, delete <integration-id>, enable <integration-id>, disable <integration-id>, and key-rotate <integration-id>. Channel-owned integrations (a ref_id starting with c_) are not among these 9; manage them with flashduty channel integration-* below.
How
settings reads back, and the secret rules:
- In the
settingsreturned bylistandinfo, every saved secret — passwords, app secrets, tokens, encryption keys, HTTP pull URL and body, header values — is shown as******; webhook and custom action endpoints and custom bodies come back as is; unset values stay empty.integration_keyis the exception and comes back as is (it authenticates inbound pushes and is not the account-levelapp_key). A script that reads credentials fromintegration info --jsontherefore gets the mask; for a new key, rotate it withkey-rotate, which invalidates the previous key immediately. - The
settingssubmitted byupdatereplaces the type-specific configuration as a whole: a known sensitive field that is omitted or sent as******keeps its stored value, and an explicit emptyheaders: {}clears headers. But a stored secret cannot be kept while its destination changes — changingendpoint,url, or a database host or port, for example, requires sending the real secret in the same call, otherwise the request is rejected. editableonly reflects object permission (no_editable: truemarks a read-only integration); write calls additionally require Integrations Manage.
channel integration — dedicated integrations
Dedicated alert integrations — the ones owned by a channel rather than by the Integration Center — are managed by 8 commands under thechannel group. The feature model is in Integrate data:
integration-list and integration-create the channel ID is positional (you can also write --channel-id), and on create the channel must be enabled. The other 6 commands take the integration_id (an integer) from a response as their positional argument; a public integration ID is not accepted.
Flags for integration-list:
The response carries
items, limit, p, and total; each row has integration_id, channel_id, name, description, plugin_type, plugin_type_name, status, settings (saved secrets shown as ******), integration_key (returned as is; it authenticates inbound pushes and is not the account-level app_key), created_at, updated_at, last_time, and last_source_time.
Fields for integration-create:
The response returns the new
integration_id and integration_key.
integration-update changes only --name, --description, and settings: the name is 2–49 characters, an empty description clears it and an omitted one keeps it, and settings replaces the type-specific configuration as a whole, where a sensitive field that is omitted or sent back as ****** keeps its stored value. It cannot move an integration to another channel, and it cannot change the integration type — recreate it in the console to change either. integration-key-rotate returns a new key and invalidates the previous one immediately, so anything pushing with the old key must be updated in the same change.
Reads (integration-list, integration-info) need the Channels Read, Channels Manage, or Integrations Read permission, and the target channel must be visible to you. Writes (integration-create, integration-update, integration-delete, integration-enable, integration-disable, integration-key-rotate) need Channels Manage and management rights on that channel. integration type-list is the shared type catalog for both families, so integration.api:read:typeList is part of all three read permissions above and a scoped App Key must be allowed to call it.
Utility commands
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.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.A generated command’s list response that carries fields beyond the row array (
items / docs / list) (for example calendar event-list’s days) prints an extra line after the row table: Also in the response: <fields> (use --json to see it). Those fields never appear in the table; use --json or --output-format toon to read them.Time-window note
Commands that query a time range print the window they actually sent to stderr in the local timezone, for examplenote: window 2026-10-08T14:00:00+08:00..2026-10-09T14:00:00+08:00 (1d, ended now). The parenthesised part carries the span and where the end sits relative to now (ended 3m ago / ends in 2h); when the window comes from a default rather than from --since/--until you typed, the note names that default (an --progress filter of open states only, or --active).
This covers incident list, alert list, alert-event list, change list, audit search, insight, oncall, monit-query (when its tool params carry an execution window), and every generated command whose --start-time/--end-time resolve. A command that leaves one side to --data or to the server default prints no note, because the window was never fully resolved by the CLI. A query with a single evaluation timestamp reads note: instant <time> (…) instead.
Use it to catch a window you did not intend: a default wider than you expected (--active widens it to 30 days), or an epoch read in the wrong timezone, which lands the window in the future and reads ends in 7h. The note goes only to stderr, so stdout stays byte-identical for jq and toon consumers.
Structured output is never clipped
json and toon output is not bounded: every row of the returned page and every field is written in full, long values are not shortened, and a list envelope gains no truncated or emitted_rows marker. The API returns one page and you get that page; total and has_next_page describe it truthfully.
You control the size: keep only the fields you need with the global --fields, lower the rows per page with --limit, and fetch the rest with --page (for example, flashduty safari session-list --limit 20 --page 2). On a few commands --fields is a request-body field selector instead (such as monit rule-update-fields) and does not apply to the output.
Field projections for structured output
--fields is a global flag (see “Global flags”): every command accepts it in json or toon output, and it takes a comma-separated list of top-level fields to keep, applied to each row of a list or to the keys of a single record. The projection runs on the response: for a list envelope (row array named items, docs, or list, with only scalar paging fields beside it) it narrows that row array and leaves the paging fields intact; a field no row of the response carries is left out and stderr reports it as matching no key, listing the keys the output does carry; output that is neither an object nor a list of objects fails the command and tells you to drop --fields. Table output ignores --fields, and stderr says so.
Without --fields, every command — the curated ones in the table below included — prints the records the API returned in full; there is no default compact projection. Each curated command defines its own --fields names (same meaning as the global flag), so a misspelled name fails immediately and lists the names that are valid. Every other command — all the generated ones included — applies --fields to the raw fields of the API response, where a name that matches no key produces the stderr note above.
For example, export only an incident ID, title, and progress:
Agent skills
Flashduty CLI ships with one agent skill,flashduty. It teaches AI coding agents, such as Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and 40+ others, to operate Flashduty from your terminal.
Install it to every detected agent on your machine in one shot:
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
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
Bulk acknowledge or close incidents
Export incident data to BI tools
Export incident data to BI tools
--page. Then process the file with jq or load it into your warehouse.Validate notification templates in CI/CD
Validate notification templates in CI/CD