CLI Reference
Every dataagent command, its flags, and exit codes.
New to the CLI? Start with Getting Started. This page lists every command.
Global flags
These apply to any command:
| Flag | Description |
|---|---|
--org <slug> | Organisation for this call. Overrides the saved org (config set-org). |
--output pretty|json | Output format. json is stable and scriptable; pretty is for humans. Default pretty. |
--color auto|always|never | When to colorise output. Default auto. --no-color is a shorthand for --color never. |
--ascii | Use ASCII symbols instead of Unicode glyphs. |
--api-url <url> | Override the API endpoint. Rarely needed — only for a non-default deployment. |
dataagent <command> --help shows a command’s own flags in your terminal at any time.
Authentication
| Command | Description |
|---|---|
dataagent login | Sign in via your browser. |
dataagent logout | Revoke the current session and clear local credentials. |
dataagent whoami | Show the signed-in identity. |
Organisation & configuration
| Command | Description |
|---|---|
dataagent orgs | List the organisations you belong to. |
dataagent config show | Print the resolved configuration and current organisation. |
dataagent config set-org <slug> | Remember an organisation so later commands don’t need --org. |
dataagent config clear | Forget the saved organisation. |
Fleet & triage
| Command | Description |
|---|---|
dataagent status [--cluster <name>] [--watch [--interval <dur>]] | Golden metrics, cluster health, and active incidents. --watch re-renders in place until Ctrl-C. |
dataagent why <id> | An incident’s summary plus its latest AI root-cause analysis. |
Incidents
dataagent incidents list [--status active] [--cluster <name>] [--limit <n>] [--offset <n>]
dataagent incidents show <id>The following mutate an incident and require the Operator role or higher — see Roles & Permissions. Each prompts for confirmation unless you pass --yes; in CI or a script, always pass --yes (the prompt refuses to run without a terminal attached).
| Command | Description |
|---|---|
dataagent incidents enrich <id> [--yes] | Trigger a fresh root-cause analysis run. An analysis already in flight is reported, not re-queued. |
dataagent incidents resolve <id> [--yes] | Mark an incident resolved. |
dataagent incidents dismiss <id> [--reason <text>] [--yes] | Dismiss an incident as not actionable. |
dataagent incidents reopen <id> [--yes] | Reopen a resolved or dismissed incident. |
dataagent incidents assign <id> <assignee> [--yes] | Assign to an organisation member, by email or user id. |
dataagent incidents unassign <id> [--yes] | Clear an incident’s assignment. |
Remediation
When an incident’s root-cause analysis produces a remediation plan, the hub proposes the ordered steps and you carry them out. The hub plans and records; it never touches your cluster.
| Command | Description |
|---|---|
dataagent remediate <id> [--dry-run] | Print the incident’s remediation plan and its ordered steps. Read-only, and available to any member. --dry-run names the preview explicitly; the bare command already only reads, so today the flag changes nothing but a notice. |
dataagent remediate report <id> [flags] | Record what actually ran against the plan. Requires the Operator role or higher — unlike the plan read. |
If the incident has no plan, the command says so and names the three possible causes, which are genuinely indistinguishable from the CLI: the incident has no root-cause analysis yet, the analysis landed and a plan is still being built, or remediation planning is not enabled for this incident’s trigger or source. The first two resolve on their own, so retry before concluding a plan will never arrive.
A plan that exists but recommends doing nothing is a different outcome. It prints under NO ACTION RECOMMENDED with the hub’s reason — an answer, not an empty result.
Reporting an attempt
dataagent remediate report writes an append-only audit row, so the hub learns what actually worked. Reporting is idempotent on --attempt-id: re-reporting one execution stores a single row rather than failing. Unlike the incident mutations above, it takes no --yes — it prompts for nothing.
| Flag | Description |
|---|---|
--tool <name> | Required. The tool that actually ran, e.g. helm_rollback. Cross-incident rollups group on this, so name it in lower_snake_case after the tool itself. |
--outcome <o> | Required. One of success, failed, verify_uncertain (it ran, recovery unconfirmed), or aborted (you started and gave up). |
--started-at <ts> | Required. RFC3339 timestamp for when execution began. |
--ended-at <ts> | RFC3339 timestamp for when it finished. Defaults to now. |
--plan-id <id> | The plan that was carried out — pass the id you were given when you fetched it. Without it, the hub binds the attempt to whichever plan is current when the report arrives, which is not necessarily the one you ran. |
--error-class <c> | One of timeout, crash, permissions, conflict, network, verify_crash. Required when --outcome=failed, rejected when --outcome=success, and optional for aborted and verify_uncertain — pass it there when you know why. |
--deviation-reason <text> | Why the tool that ran differed from the plan. Plan steps name no tool, so this is the only record that a substitution happened. |
--attempt-id <id> | Idempotency key. Derived from the incident, tool, and start time when omitted, so an interrupted report can simply be retried. |
dataagent remediate report <incident-id> \
--plan-id <the id you read> \
--tool helm_rollback --outcome success \
--started-at 2026-09-08T10:03:11Z --ended-at 2026-09-08T10:04:02ZSignals
The org-wide feed of raw detections that roll up into incidents:
| Command | Description |
|---|---|
dataagent signals list [--severity <s>] [--status <s>] [--source <s>] [--namespace <ns>] [--cluster <name>] [--limit <n>] [--offset <n>] | List signals. --severity, --status, and --source are repeatable filters. |
dataagent signals tail [--interval <dur>] [--ndjson] | Follow new or re-fired signals by polling. --ndjson emits one JSON object per line for piping; --output json is not supported here since tail is a stream, not a single document. |
API tokens
For CI and other non-interactive callers — see Getting Started: Non-interactive use.
| Command | Description |
|---|---|
dataagent tokens create --name <n> [--expires-in <d>] | Mint a token. Printed once — it cannot be retrieved again. --expires-in accepts 24h, 30d, 12w, or omit for no expiry. |
dataagent tokens list | List tokens registered to your account (never shows the raw value). |
dataagent tokens revoke <name-or-id> [--yes] | Revoke a token permanently. Matched by name first, then id. |
Shell completion
| Command | Description |
|---|---|
dataagent completion bash|zsh|fish | Print a completion script to stdout. |
dataagent completion install [bash|zsh|fish] | Write it to the conventional path for your shell and print activation steps. Shell is detected from $SHELL when omitted. |
AI assistant integration
A Skill teaches Claude Code or Cursor (2.4+) the dataagent CLI and API — it triggers automatically when you ask about orgs, incidents, signals, or metrics, when you ask to fix or roll back a failing workload, or when you ask about minting tokens.
| Command | Description |
|---|---|
dataagent skill update [--dir <dir>] | Install the skill, or refresh an installed one. Prints installed, updated or up to date. Defaults to ~/.claude/skills/dataagent; no sign-in needed. |
dataagent skill update # Claude Code, personal (all projects)
dataagent skill update --dir .claude/skills/dataagent # Claude Code, this project only
dataagent skill update --dir .cursor/skills/dataagent # Cursor (2.4+)Both tools read the same file. The skill keeps itself current: its first instruction tells the assistant to run dataagent skill update on its own directory before using it.
Without the CLI, download the same file directly:
# Claude Code
mkdir -p ~/.claude/skills/dataagent
curl -fsSL https://app.data-agent.co/api/v1/skills/dataagent -o ~/.claude/skills/dataagent/SKILL.md
# Cursor (2.4+)
mkdir -p .cursor/skills/dataagent
curl -fsSL https://app.data-agent.co/api/v1/skills/dataagent -o .cursor/skills/dataagent/SKILL.mdversion
Prints the CLI’s version, commit, and build date.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic error |
2 | Usage error — bad flag, argument, or configuration |
3 | Not signed in, or the session expired |
4 | Not found |
5 | Permission denied |
6 | Conflict (e.g. an incident already in its target state) |
7 | Rate limited |
A rate-limited command also prints how long to wait, when the server provides it.