It's easy to assume that once you have a web console and an Open API, a command-line tool is redundant. The web is for clicking, the API is for programs, and the CLI in between feels like a layer nobody needs.
But when you actually sit next to an on-call SRE during an incident, things aren't that clean. The engineer is staring at logs, kubectl, and a string of greps in their terminal. An alert fires, and the first thing they want is not to switch to a browser, log into a console, find the right collaboration space, and dig out the incident. It's to acknowledge it, read the timeline, and pull up similar past incidents without leaving the context they're already in. Every window switch is a break in attention, and broken attention is exactly what incident response can least afford.
That's the first reason flashduty-cli exists: to keep incident response where the engineer already is, in the terminal.
Why a CLI, and not "just the API"
You could argue: I'll wrap the API in a script myself. You can. But an Open API is raw material, not a tool.
Flashduty's API returns structured data. The fields are complete, but they aren't friendly to a human reading them in a shell. To make it comfortable in a terminal, you have to handle pagination, parse time, render piles of JSON into aligned tables, truncate long fields, and still leave a clean exit for jq. This "last mile" is grunt work, and having every team redo it is enormous waste. The CLI paves that last mile once:
flashduty incident list # last 24h by default
flashduty incident get <id> # a single ID auto-switches to a vertical detail view
flashduty incident timeline <id> # view the timeline
flashduty incident similar <id> # pull up similar past incidentsOutput defaults to an aligned table for humans, with long fields truncated; add --json for full data you can pipe straight into jq. Time flags don't force you to compute Unix timestamps either. 24h, 168h, 2026-04-01, and 2026-04-01 10:00:00 all parse. The point is to absorb the API's complexity, not pass it through to the user.
There's also an engineering boundary we wrote straight into our agent instructions: the CLI does not implement API endpoint clients itself. All access to the Flashduty Open API goes through flashduty-sdk; the CLI only does command parsing, output formatting, and orchestration. The SDK stays strictly 1:1 with the API, while consumer-side conveniences (like resolving a collaboration space ID by name) live in the CLI layer. The payoff: when the API evolves, you change the SDK and the CLI rides along, with no half-built HTTP adapters maintained in two places.
The decision that actually mattered: the CLI is an AI agent's tool surface
If the story stopped there, flashduty-cli would be a respectable ops tool and nothing more. What makes it different is a second call we made.
More and more, there's an AI agent sitting in the engineer's terminal too.
Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf. These coding assistants can already read your repo, run commands, and edit files. When a production alert fires, engineers increasingly turn to the agent beside them: "What's going on with this incident, who's on call, does it look like last time?"
The problem is that an agent has no idea how to operate Flashduty by default. It can guess at the API, hand-stitch a curl, or, more likely, not know the platform exists at all, or get it wrong in a way that breaks something. For instance, merging two incidents without confirmation, when a merge is irreversible.
So we did one thing: we turned "how to use Flashduty" into a capability an agent can load. flashduty-cli ships 10 agent skills you install into your agent with one command:
npx skills add flashcatcloud/flashduty-cli -y -gThe installer auto-detects which agents you have and distributes the skills to all of them. It's currently compatible with 41+ coding agents. Afterward, an agent that knew nothing about Flashduty now knows which command to use, how to fill the flags, and which actions must be confirmed with a human first.
What's actually inside a skill
These 10 skills aren't a re-read of the command list. What we really pour into them is a mental model and a set of safety boundaries, the things an experienced on-call engineer already carries in their head.
The foundation skill, flashduty-shared, opens by making Flashduty's three-layer noise-reduction model explicit: raw alert events dedup by alert_key into alerts; alerts aggregate by grouping rules into actionable incidents; one incident can hold anywhere from 1 to 5,000 alerts. Once an agent understands this data model, it stops asking at the wrong layer when it drills down or rolls up.
The other nine skills are split by responsibility: incident lifecycle, alert investigation, change tracking, on-call queries, collaboration spaces and escalation rules, status page management, MTTA/MTTR analytics, team and member audit, notification template validation. Each skill hands the agent only the most relevant commands and idioms for its scope, instead of dumping the full set of 200-plus commands at once. The agent sees only the right tool at the right moment.
Most important, though, are the safety rules. In the foundation skill we hard-code a set of constraints written for the AI, such as:
- Never create or close an incident without explicit user confirmation;
- Never merge incidents or alerts, because merges are irreversible;
- Always list what will be affected before any destructive or mutating operation;
- When in doubt, list first, then act, and prefer read-only operations.
These aren't hints for a human; they're a "don't make things worse" checklist for the model. The most dangerous thing an autonomous agent does is confidently execute an irreversible action, so we'd rather it ask one more time.
A detail that matters for agents: tokens are a cost too
Building a tool for agents versus for humans diverges in one very concrete place: for an agent, the size of the output is money and context window, directly.
So beyond table and JSON, the CLI offers a third output format, TOON (Token-Oriented Object Notation). Like JSON, it's complete, untruncated, machine-readable data. But for uniform arrays, list output where every row has the same fields, it declares the field names once in a header instead of repeating the keys on every row. For the same page of incidents, TOON costs materially fewer tokens than JSON.
flashduty incident list --output-format toonIt's a tiny feature, but it reflects a judgment: when the primary consumer of a tool shifts from a human to a model, the function you optimize has to shift too. Humans care about readability; models care about the value per token.
The unglamorous reliability that decides everything
Finally, the thing that sounds boring but most determines whether a tool is good to use: the reliability of completion and --help.
The CLI is built on Cobra, with shell completion for bash, zsh, fish, and powershell. But with completion, "generated" is not "working." The default command has to be installed correctly, and enum-valued flags have to actually complete their values, or the user stalls mid-keystroke and the experience collapses. It's awkward for a human; it's fatal for an agent. The only reliable way an agent explores an unfamiliar CLI is --help. If a subcommand's help text is missing a flag, or its description doesn't match real behavior, the model will build a command from wrong information and fail.
So we treat every subcommand, flag, and enum value that appears in help text as a contract the agent will trust verbatim: what the help says has to be exactly what the tool does. This kind of polish never makes a headline, but it's the difference between an agent getting the command right on the first try and grinding through three rounds of trial and error.
A short conclusion
Where flashduty-cli stands today (v1.3.4), we're clear on what it is: first, a tool sharp enough that an SRE never has to leave the terminal to respond to an incident; and at the same time, the standard entry point for AI coding agents to operate Flashduty. Full coverage of the Flashduty Open API, a one-line curl install, and 10 skills that drop straight into 41+ agents. Stitched together, these all come from the same call: incident response should happen where the engineer (and their AI sidekick) already is, not in yet another browser tab.
If you want to try it, one line installs it:
curl -sSL https://raw.githubusercontent.com/flashcatcloud/flashduty-cli/main/install.sh | shThe repo and docs are at github.com/flashcatcloud/flashduty-cli.
