Skip to content

Commit 7572961

Browse files
ysyneuysyneu
authored
docs(developer): add Flashduty CLI guide (#54)
Document the newly released flashduty-cli command-line tool: installation on macOS/Linux/Windows, APP Key authentication, the full command catalog (incident, change, member, team, channel, escalation-rule, field, statuspage with Atlassian migration, template), output formats, agent skills, and common workflows. Register the new page under the Developer group in docs.json and add a CLI card + section to the developer overview in both Chinese and English.
1 parent a67dd4c commit 7572961

5 files changed

Lines changed: 684 additions & 4 deletions

File tree

‎docs.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@
6161
"pages": [
6262
"zh/developer/overview",
6363
"zh/openapi",
64+
"zh/developer/cli",
6465
"zh/developer/mcp-server",
6566
"zh/developer/terraform"
6667
]
@@ -1011,6 +1012,7 @@
10111012
"pages": [
10121013
"en/developer/overview",
10131014
"en/openapi",
1015+
"en/developer/cli",
10141016
"en/developer/mcp-server",
10151017
"en/developer/terraform"
10161018
]

‎en/developer/cli.mdx‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
---
2+
title: Command-line tool
3+
description: "Manage incidents, on-call schedules, status pages, and notification templates from your terminal with Flashduty CLI"
4+
keywords: ["CLI", "command line", "flashduty-cli", "terminal"]
5+
---
6+
7+
## Overview
8+
9+
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.
10+
11+
The tool is open source at [flashcatcloud/flashduty-cli](https://github.com/flashcatcloud/flashduty-cli) and supports macOS, Linux, and Windows.
12+
13+
## Installation
14+
15+
<Tabs>
16+
<Tab title="macOS / Linux">
17+
```bash
18+
curl -sSL https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.sh | sh
19+
```
20+
21+
Installs to `/usr/local/bin` by default. Override with the `FLASHDUTY_INSTALL_DIR` environment variable.
22+
</Tab>
23+
24+
<Tab title="Windows (PowerShell)">
25+
```powershell
26+
irm https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.ps1 | iex
27+
```
28+
29+
Installs to `~\.flashduty\bin` by default. Override with the `FLASHDUTY_INSTALL_DIR` environment variable.
30+
</Tab>
31+
32+
<Tab title="Go Install">
33+
```bash
34+
go install github.com/flashcatcloud/flashduty-cli/cmd/flashduty@latest
35+
```
36+
37+
Make sure `$(go env GOPATH)/bin` is on your `PATH`.
38+
</Tab>
39+
40+
<Tab title="Manual download">
41+
Grab the binary for your platform from [GitHub Releases](https://github.com/flashcatcloud/flashduty-cli/releases), extract it, and place it on your `PATH`.
42+
</Tab>
43+
</Tabs>
44+
45+
### Installer options
46+
47+
| Variable | Description | Default |
48+
|----------|-------------|---------|
49+
| `FLASHDUTY_VERSION` | Install a specific version, e.g. `v0.6.0` | latest |
50+
| `FLASHDUTY_INSTALL_DIR` | Custom install directory | `/usr/local/bin` (shell), `~\.flashduty\bin` (PowerShell) |
51+
52+
## Authentication
53+
54+
### Log in
55+
56+
```bash
57+
flashduty login
58+
```
59+
60+
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**.
61+
62+
### Credential resolution order
63+
64+
The CLI resolves credentials in the following order (highest priority first):
65+
66+
1. `--app-key` command-line flag (hidden, for scripting)
67+
2. `FLASHDUTY_APP_KEY` environment variable
68+
3. Config file `~/.flashduty/config.yaml` (written by `flashduty login`)
69+
70+
### Config file
71+
72+
Stored at `~/.flashduty/config.yaml` with `0600` permissions:
73+
74+
```yaml
75+
app_key: your_app_key
76+
base_url: https://api.flashcat.cloud
77+
```
78+
79+
### Config commands
80+
81+
```bash
82+
flashduty config show # Print current config (APP Key masked)
83+
flashduty config set app_key KEY # Set the APP Key
84+
flashduty config set base_url URL # Override the API endpoint
85+
```
86+
87+
## Global flags
88+
89+
All subcommands accept these flags:
90+
91+
| Flag | Description |
92+
|------|-------------|
93+
| `--json` | Output as JSON for parsing with `jq` or similar tools |
94+
| `--no-trunc` | Disable column truncation in table output |
95+
| `--base-url` | Override the API endpoint (for private deployments) |
96+
97+
## Command catalog
98+
99+
### incident — Incident lifecycle
100+
101+
```bash
102+
flashduty incident list [flags] # List incidents (default: last 24h)
103+
flashduty incident get <id> [<id2>...] # Show incident details (vertical view for a single ID)
104+
flashduty incident create [flags] # Create an incident (interactive if flags are missing)
105+
flashduty incident update <id> [flags] # Update incident fields
106+
flashduty incident ack <id> [<id2>...] # Acknowledge incidents
107+
flashduty incident close <id> [<id2>...] # Close (resolve) incidents
108+
flashduty incident timeline <id> # View an incident timeline
109+
flashduty incident alerts <id> # List alerts associated with an incident
110+
flashduty incident similar <id> # Find similar historical incidents
111+
```
112+
113+
Common filter flags for `incident list`:
114+
115+
| Flag | Description | Default |
116+
|------|-------------|---------|
117+
| `--progress` | Progress filter: `Triggered`, `Processing`, `Closed` | all |
118+
| `--severity` | Severity filter: `Critical`, `Warning`, `Info` | all |
119+
| `--channel` | Filter by channel ID | - |
120+
| `--title` | Search by title keyword | - |
121+
| `--since` | Start time (duration, date, datetime, or unix timestamp) | `24h` |
122+
| `--until` | End time | `now` |
123+
| `--limit` | Max results | `20` |
124+
| `--page` | Page number | `1` |
125+
126+
Time format examples: `5m`, `1h`, `24h`, `168h`, `2026-04-01`, `2026-04-01 10:00:00`, `1712000000`.
127+
128+
### change — Change records
129+
130+
```bash
131+
flashduty change list [flags] # List change records (deployments, config changes)
132+
```
133+
134+
Supports `--channel`, `--since`, `--until`, `--type`, `--limit`, `--page`.
135+
136+
### member — Member queries
137+
138+
```bash
139+
flashduty member list [flags] # List members
140+
```
141+
142+
Supports `--name`, `--email`, `--page`.
143+
144+
### team — Team queries
145+
146+
```bash
147+
flashduty team list [flags] # List teams with members
148+
```
149+
150+
Supports `--name`, `--page`.
151+
152+
### channel — Channel queries
153+
154+
```bash
155+
flashduty channel list [flags] # List channels
156+
```
157+
158+
Supports `--name`.
159+
160+
### escalation-rule — Escalation rule queries
161+
162+
```bash
163+
flashduty escalation-rule list --channel <id> # By channel ID
164+
flashduty escalation-rule list --channel-name <name> # By channel name (auto-resolved)
165+
```
166+
167+
### field — Custom field queries
168+
169+
```bash
170+
flashduty field list [flags] # List custom field definitions
171+
```
172+
173+
Supports `--name`.
174+
175+
### statuspage — Status page management
176+
177+
```bash
178+
flashduty statuspage list [--id <ids>] # List status pages
179+
flashduty statuspage changes --page-id <id> --type <incident|maintenance> # List active changes
180+
flashduty statuspage create-incident --page-id <id> --title <title> # Create a status page incident
181+
flashduty statuspage create-timeline --page-id <id> --change <id> --message <msg> # Append a timeline update
182+
```
183+
184+
#### Migrate from Atlassian Statuspage
185+
186+
Migration jobs run asynchronously. After kicking off a job, poll progress with `migrate status`:
187+
188+
```bash
189+
# 1. Migrate structure and history
190+
flashduty statuspage migrate structure \
191+
--from atlassian \
192+
--source-page-id page_123 \
193+
--api-key $ATLASSIAN_STATUSPAGE_API_KEY
194+
195+
# 2. Check job status
196+
flashduty statuspage migrate status --job-id <job_id>
197+
198+
# 3. Migrate email subscribers
199+
flashduty statuspage migrate email-subscribers \
200+
--from atlassian \
201+
--source-page-id page_123 \
202+
--target-page-id <target_page_id> \
203+
--api-key $ATLASSIAN_STATUSPAGE_API_KEY
204+
205+
# 4. Cancel a running job
206+
flashduty statuspage migrate cancel --job-id <job_id>
207+
```
208+
209+
### template — Notification templates
210+
211+
```bash
212+
flashduty template get-preset --channel <channel> # Get preset template code
213+
flashduty template validate --channel <channel> --file <path> # Validate and preview a template
214+
flashduty template variables [--category <category>] # List available template variables
215+
flashduty template functions [--type custom|sprig|all] # List available template functions
216+
```
217+
218+
Supported channels: `dingtalk`, `dingtalk_app`, `feishu`, `feishu_app`, `wecom`, `wecom_app`, `slack`, `slack_app`, `telegram`, `teams_app`, `email`, `sms`, `zoom`.
219+
220+
### Utility commands
221+
222+
```bash
223+
flashduty login # Interactive login
224+
flashduty config show # Show current configuration
225+
flashduty config set # Set a configuration value
226+
flashduty version # Print version information
227+
flashduty completion # Generate shell completions (bash/zsh/fish/powershell)
228+
```
229+
230+
Enable shell completion (zsh example):
231+
232+
```bash
233+
flashduty completion zsh > "${fpath[1]}/_flashduty"
234+
```
235+
236+
## Output formats
237+
238+
The CLI emits output in three shapes so it fits different consumers:
239+
240+
<Tabs>
241+
<Tab title="Table (default)">
242+
Human-readable, aligned columns, long fields truncated.
243+
244+
```
245+
ID TITLE SEVERITY PROGRESS CHANNEL CREATED
246+
inc_abc123 DB connection timeout Critical Triggered Production 2026-04-10 10:23
247+
inc_def456 High memory usage Warning Processing Staging 2026-04-10 09:15
248+
Showing 2 results (page 1, total 2).
249+
```
250+
</Tab>
251+
252+
<Tab title="JSON (--json)">
253+
Machine-parseable, full payload, no truncation. Ideal for scripts and CI/CD pipelines.
254+
255+
```bash
256+
flashduty incident list --json | jq '.[].title'
257+
```
258+
</Tab>
259+
260+
<Tab title="Full table (--no-trunc)">
261+
Table view with no column truncation — useful for copy-paste or wide terminals.
262+
</Tab>
263+
</Tabs>
264+
265+
## Agent skills
266+
267+
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.
268+
269+
Install skills to every detected agent on your machine in one shot:
270+
271+
```bash
272+
npx skills add flashcatcloud/flashduty-cli -y -g
273+
```
274+
275+
Available skills:
276+
277+
| Skill | Scope |
278+
|-------|-------|
279+
| `flashduty-shared` | Foundation: authentication, three-layer noise model, global flags, safety rules |
280+
| `flashduty-incident` | Incident lifecycle: triage, investigate, resolve, merge, snooze, reassign |
281+
| `flashduty-alert` | Alert and alert event investigation: drill down, trace, merge |
282+
| `flashduty-change` | Change event tracking and deployment frequency trends |
283+
| `flashduty-oncall` | On-call schedule queries: who is on call, shift details |
284+
| `flashduty-channel` | Channel and escalation rule lookups |
285+
| `flashduty-statuspage` | Status page management and Atlassian → Flashduty migration |
286+
| `flashduty-insight` | Analytics: MTTA/MTTR, noise reduction, notification trends |
287+
| `flashduty-admin` | Team/member lookups and audit log search |
288+
| `flashduty-template` | Notification template validation and preview |
289+
290+
## Common workflows
291+
292+
<AccordionGroup>
293+
<Accordion title="Attach a CLI link to notifications">
294+
Use `flashduty incident get <id>` to fetch incident details from the terminal. Embed the snippet into notification templates so responders can copy-paste it.
295+
</Accordion>
296+
297+
<Accordion title="Bulk acknowledge or close incidents">
298+
```bash
299+
flashduty incident ack inc_001 inc_002 inc_003
300+
flashduty incident close inc_001 inc_002 inc_003
301+
```
302+
</Accordion>
303+
304+
<Accordion title="Export incident data to BI tools">
305+
```bash
306+
flashduty incident list --since 168h --limit 500 --json > incidents.json
307+
```
308+
Then process the file with `jq` or load it into your warehouse.
309+
</Accordion>
310+
311+
<Accordion title="Validate notification templates in CI/CD">
312+
```bash
313+
flashduty template validate --channel feishu --file templates/feishu.yaml
314+
```
315+
Run this in CI to catch syntax or field errors as soon as a template is committed.
316+
</Accordion>
317+
</AccordionGroup>
318+
319+
<Tip>
320+
Full source, releases, and issue tracking live on the [GitHub repository](https://github.com/flashcatcloud/flashduty-cli).
321+
</Tip>

‎en/developer/overview.mdx‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,21 @@
11
---
22
title: Developer tools
3-
description: "Manage Flashduty resources programmatically via API, MCP Server, and Terraform Provider"
3+
description: "Manage Flashduty resources programmatically via API, CLI, MCP Server, and Terraform Provider"
44
---
55

66
## Overview
77

88
Flashduty provides multiple developer tools to help you programmatically manage incident response workflows, automate operations, and integrate Flashduty into your existing toolchain.
99

10-
<CardGroup cols={3}>
10+
<CardGroup cols={2}>
1111
<Card title="Open API" icon="code" href="/en/openapi/introduction">
1212
RESTful API for accessing and managing Flashduty entities including incidents, alerts, channels, schedules, and more.
1313
</Card>
1414

15+
<Card title="Command-line tool" icon="terminal" href="/en/developer/cli">
16+
Flashduty CLI for managing incidents, on-call schedules, status pages, and notification templates from your terminal — runs on macOS, Linux, and Windows with 10 built-in AI coding-agent skills.
17+
</Card>
18+
1519
<Card title="MCP Server" icon="robot" href="https://github.com/flashcatcloud/flashduty-mcp-server">
1620
Model Context Protocol server that connects Flashduty APIs to AI tools like Claude and Cursor, enabling natural language incident management and status page operations.
1721
</Card>
@@ -34,6 +38,20 @@ The Flashduty Open API follows RESTful conventions and supports APP Key authenti
3438
Visit the [API documentation](/en/openapi/introduction) for complete endpoint references and request examples.
3539
</Tip>
3640

41+
## Command-line tool
42+
43+
Flashduty CLI (`flashduty`) is a command-line tool for managing the incident lifecycle, querying on-call schedules, publishing status pages, and debugging notification templates from your terminal. It runs on macOS, Linux, and Windows, and ships with 10 agent skills so it plugs directly into AI coding agents like Claude Code, Cursor, Codex, and Gemini CLI.
44+
45+
Install with one command:
46+
47+
```bash
48+
curl -sSL https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.sh | sh
49+
```
50+
51+
<Tip>
52+
See the [Command-line tool](/en/developer/cli) guide for the full installation matrix, command catalog, and best practices.
53+
</Tip>
54+
3755
## MCP Server
3856

3957
The Flashduty MCP Server implements the [Model Context Protocol](https://modelcontextprotocol.io/), providing AI tools with 18 tools across 6 functional modules:

0 commit comments

Comments
 (0)