> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-docs-compliance-guide-refine.mintlify.site/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) |

## 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                                     | -       |
| `--title`    | Search by title keyword                                  | -       |
| `--since`    | Start time (duration, date, datetime, or unix timestamp) | `24h`   |
| `--until`    | End time                                                 | `now`   |
| `--limit`    | Max results                                              | `20`    |
| `--page`     | Page number                                              | `1`     |

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

### change — Change records

```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 `--name`, `--email`, `--page`.

### team — Team queries

```bash theme={null}
flashduty team list [flags]      # List teams with members
```

Supports `--name`, `--page`.

### channel — Channel queries

```bash theme={null}
flashduty channel list [flags]   # List channels
```

Supports `--name`.

### escalation-rule — Escalation rule queries

```bash theme={null}
flashduty escalation-rule list --channel <id>          # By channel ID
flashduty escalation-rule list --channel-name <name>   # By channel name (auto-resolved)
```

### field — Custom field queries

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

Supports `--name`.

### statuspage — Status page management

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

#### Migrate from Atlassian Statuspage

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

```bash theme={null}
# 1. Migrate structure and history
flashduty statuspage migrate structure \
  --from atlassian \
  --source-page-id page_123 \
  --api-key $ATLASSIAN_STATUSPAGE_API_KEY

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

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

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

### template — Notification templates

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

### Full command coverage

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

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

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

```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 completion     # Generate shell completions (bash/zsh/fish/powershell)
```

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>