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.

change — Change records

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

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

member — Member queries

flashduty member list [flags]    # List members

Supports --query (free-text search by name or email), --role-id, --page, --limit, --orderby, --asc.

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 --team-id, --team-name, or --ref-id to identify the team (exactly one required). 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 (email addresses to invite as members)
--ref-id (external reference ID for HR system integration)

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).

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, subscriber-export.

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":"disk.usage"}]}'

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 (Prometheus, VictoriaLogs, Loki, MySQL) directly, bypassing the alert-rule layer.

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

Common flags for diagnose:

Flag	Description
`--ds-type`	Datasource type (required): `prometheus`, `victorialogs`, `loki`, `mysql`
`--ds-name`	Datasource name as configured in the console (required)
`--input-query`	Filter-only log query or matrix PromQL (required)
`--time-start`	Window start — relative (`15m`, `1h`), unix seconds, or `now` (default `15m`)
`--time-end`	Window end — relative, unix seconds, or `now` (default `now`; window capped at 6h)
`--operation`	`log_patterns` or `metric_trends` (inferred from `--ds-type` when omitted)

rows requires --ds-type, --ds-name, and --expr (query expression). Use --args KEY=VALUE (repeatable) for parameterized queries.

Full command coverage

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

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

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

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

Utility commands

flashduty login          # Interactive login
flashduty config show    # Show current configuration
flashduty config set     # Set a configuration value
flashduty version        # Print version information
flashduty 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, full payload, no truncation. Ideal for scripts and CI/CD pipelines.

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

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

flashduty incident list --output-format toon

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

Agent skills

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

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

Available skills:

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

Common workflows

Attach a CLI link to notifications

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

Bulk acknowledge or close incidents

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

Export incident data to BI tools

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

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

Validate notification templates in CI/CD

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

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

Full source and issue tracking live on the GitHub repository.

​Overview

​Installation

​Installer options

​Authentication

​Log in

​Credential resolution order

​Config file

​Config commands

​Global flags

​Command catalog

​incident — Incident lifecycle

​change — Change records

​member — Member queries

​team — Team management

​channel — Channel queries

​channel escalate-rule-list — Escalation rule queries

​field — Custom field queries

​status-page — Status page management

​Migrate from Atlassian Statuspage

​template — Notification templates

​session — AI SRE sessions

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

​monit-query — Monitoring datasource queries

​Full command coverage

​Utility commands

​Output formats

​Agent skills

​Common workflows

Overview

Installation

Installer options

Authentication

Log in

Credential resolution order

Config file

Config commands

Global flags

Command catalog

incident — Incident lifecycle

change — Change records

member — Member queries

team — Team management

channel — Channel queries

channel escalate-rule-list — Escalation rule queries

field — Custom field queries

status-page — Status page management

Migrate from Atlassian Statuspage

template — Notification templates

session — AI SRE sessions

monit-agent — On-box host/database diagnostics

monit-query — Monitoring datasource queries

Full command coverage

Utility commands

Output formats

Agent skills

Common workflows