Work with an AI agent

For AI agents

xdr is designed to be driven by an agent. Point the agent at AGENTS.md — it covers invocation rules, output shapes, exit codes, and the investigation methodology in docs/investigation.md and playbooks/. The short version:

Large reads emit JSON receipts and previews; progress and warnings go to stderr. Lifecycle and raw-render commands have their own output shapes documented in AGENTS.md. Never merge streams with 2>&1.
Progress is auto-silenced when stdout is piped; --quiet suppresses progress, --no-quiet forces it on. Configuration warnings can still appear on stderr.
xdr prompts only when both stdin and stdout are TTYs; otherwise (or with --no-interactive) it never prompts. Commands that would ask for confirmation (response actions, incidents update, results prune) refuse with exit 6 unless --yes is passed. auth login and auth portal-cookie are interactive flows for a human; agents should ask rather than treat --no-interactive as unattended sign-in.
Failures before durable output are one JSON error line with a stable code and exit_code; usage errors may include a corrected_argv hint. Operations the selected backend cannot perform return BACKEND_CAPABILITY_UNAVAILABLE and never fall back to the other backend.
Explicit session end emits a closure record with feedback instructions, then a maintenance record. Upkeep can return exit 14 after the session is safely closed; cancellation returns 130. Do not retry the session end.
Exit codes: 0 ok · 1 internal · 2 auth · 3 upstream API · 4 config · 5 query · 6 usage · 7 permission · 8 not found · 9 rate-limited · 10 timeout · 11 network · 12 artifact I/O · 13 conflict · 14 partial success · 130 cancelled.

# In a Claude Code / Copilot CLI / Codex prompt:
"Use xdr-cli to investigate incident 4421: run `xdr investigate --auto-enrich 4421`,
read the receipt's data_path, and summarise the alerts, entities, and recommended
actions. Do not run any `xdr device` command without asking me."