> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line tool

> Manage incidents, on-call schedules, status pages, and notification templates from your terminal with Flashduty CLI

## 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](https://github.com/flashcatcloud/flashduty-cli) and supports macOS, Linux, and Windows.

## Installation

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://static.flashcat.cloud/flashduty-cli/install.ps1 | iex
    ```

    Installs to `~\.flashduty\bin` by default. Override with the `FLASHDUTY_INSTALL_DIR` environment variable.
  </Tab>

  <Tab title="Manual download">
    Read the latest version from the [CDN latest version pointer](https://static.flashcat.cloud/flashduty-cli/releases/latest), then download the matching asset from `https://static.flashcat.cloud/flashduty-cli/releases/download/<version>/<asset>`, extract it, and place it on your `PATH`.
  </Tab>
</Tabs>

### 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

```bash theme={null}
flashduty login
```

When prompted, paste your APP Key. To obtain one, sign in to the [Flashduty console](https://console.flashcat.cloud) and copy your APP Key from **Profile > Personal Info**.

### Credential resolution order

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

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

### Config file

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

```yaml theme={null}
app_key: your_app_key
base_url: https://api.flashcat.cloud
```

### Config commands

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
flashduty change list [flags]    # List change records (deployments, config changes)
```

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

### member — Member queries

```bash theme={null}
flashduty member list [flags]    # List members
```

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

### team — Team management

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
flashduty field list [flags]     # List custom field definitions
```

Supports `--name`.

### status-page — Status page management

```bash theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
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.

```bash theme={null}
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`  |

<Note>
  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.
</Note>

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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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`:

```bash theme={null}
flashduty --help                 # List all top-level command groups
flashduty safari --help          # AI SRE generated commands
flashduty alert --help           # Alert-related generated commands
```

### Utility commands

```bash theme={null}
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)
```

<Note>
  `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.
</Note>

Enable shell completion (zsh example):

```bash theme={null}
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:

<Tabs>
  <Tab title="Table (default)">
    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).
    ```
  </Tab>

  <Tab title="JSON (--json / --output-format json)">
    Machine-parseable, full payload, no truncation. Ideal for scripts and CI/CD pipelines.

    ```bash theme={null}
    flashduty incident list --json | jq '.[].title'
    ```
  </Tab>

  <Tab title="TOON (--output-format toon)">
    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.

    ```bash theme={null}
    flashduty incident list --output-format toon
    ```

    <Note>
      TOON cannot be parsed directly by `jq`; use `--json` when you need to pipe into `jq`.
    </Note>
  </Tab>

  <Tab title="Full table (--no-trunc)">
    Table view with no column truncation — useful for copy-paste or wide terminals.
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Bulk acknowledge or close incidents">
    ```bash theme={null}
    flashduty incident ack inc_001 inc_002 inc_003
    flashduty incident close inc_001 inc_002 inc_003
    ```
  </Accordion>

  <Accordion title="Export incident data to BI tools">
    ```bash theme={null}
    flashduty incident list --since 168h --limit 500 --json > incidents.json
    ```

    Then process the file with `jq` or load it into your warehouse.
  </Accordion>

  <Accordion title="Validate notification templates in CI/CD">
    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

<Tip>
  Full source and issue tracking live on the [GitHub repository](https://github.com/flashcatcloud/flashduty-cli).
</Tip>