Command reference

Command	Description
`xdr auth login / status / logout`	Interactive sign-in for the official backend (device-code fallback), status for both backends, clear the selected backend’s credentials
`xdr auth portal-cookie SOURCE / portal-logout`	Import (`--verify`, `--keep-source`) or remove a portal-session cookie — see docs/portal_cookie.md
`xdr incidents list`	`--since`, `--severity`, `--status`, `--assigned-to`, `--limit`
`xdr incidents show ID [--expand alerts]` / `update ID`	View (alerts include their evidence); update `--status`, `--classification`, `--determination`, `--comment` (`--dry-run`, `--yes`)
`xdr alerts list / show ID`	`--since`, `--severity`, `--service`, `--limit`
`xdr investigate ID [--auto-enrich]`	Guided investigation; without `--auto-enrich` it asks which queries to run (all, when non-interactive)
`xdr hunt run KQL`	Ad-hoc advanced hunting (`--from-file`, `--from-stdin`, `--timeout`, `--raw`)
`xdr hunt library-show NAME -p k=v`	Render a library query’s resolved KQL without running it
`xdr library list / show NAME / run NAME`	Browse (`--search`, `--tier`) and run library queries (`-p key=value`, repeatable; `--timeout`, `--raw`)
`xdr lists init`	Seed `~/.xdr-cli/lists/` reference data used by library queries (`--force --yes` to overwrite)
`xdr device show / isolate / unisolate / scan / restrict / unrestrict / collect-package / action-status`	Device details and response actions
`xdr device download-package ACTION --device ID --output PATH`	Download a completed investigation ZIP (cookie backend; `--force`, `--max-bytes`)
`xdr device timeline DEVICE`	Download a device’s portal timeline (unofficial API) — docs/device_timeline.md
`xdr domains list [--source all\|entra\|active-directory]`	Source-labelled Entra and observed AD domains (AD is cookie-only)
`xdr results list / show / head / rows / query / shape / prune`	Browse and manage local result artifacts (`rows --type/--offset/--limit`)
`xdr schema status` / `xdr schema diagnostics`	Cache-only state of the schema cache and semantic graph; `status` prints the exact `next_command`
`xdr schema collect` [`--local-only` \| `--plan-only` \| `--explore`]	Mine saved results, validate focused pairs, or discover additional identifier locations; rerun to continue
`xdr schema pivot FIELD` / `xdr schema path A B` / `xdr schema discoveries`	Explain reviewed and empirical identifier routes
`xdr schema refresh` / `tables` / `show TABLE`	Refresh and query the physical table/column cache (`--search`)
`xdr schema observe` / `candidate-review` / `candidate-proposal`	Explicit identifier probes, private evidence review, non-promoting core proposals
`xdr schema export-opengraph PATH`	Export the graph for BloodHound (`--include-tenant`, `--include-candidates`, `--custom-nodes`)
`xdr schema bundle export` / `xdr schema bundle inspect` / `xdr schema bundle import`	Move schema state between machines as a content-bound archive
`xdr schema repair-overlay` / `xdr schema migrate-cache` / `prune-evidence` / `correlate` / `validate-core`	Local repair, evidence retirement, offline correlation, packaged-graph validation
`xdr session start / end / resume / list / show / feedback`	Sessions, learning mode, append-only feedback — see docs/sessions.md
`xdr history [stats]`, `xdr annotate`	Browse recorded invocations, aggregate failure and coverage metrics, record a lesson

Global options: --backend auto|official|portal-cookie, --quiet/-q, --no-quiet, --no-interactive, --debug, --rationale TEXT (record intent on the session log), --version/-v. Every command has --help.

Response actions

xdr device show <device-id>
xdr device isolate <device-id> --comment "Incident 42" --dry-run   # preview
xdr device isolate <device-id> --comment "Incident 42" --yes       # do it
xdr device unisolate <device-id> --comment "Remediated" --yes
xdr device scan <device-id> --scan-type Full
xdr device restrict <device-id> --comment "Suspicious activity" --yes
xdr device unrestrict <device-id> --comment "Recovery approved" --yes
xdr device collect-package <device-id>
xdr device action-status <action-id>
xdr device download-package <action-id> --device <device-id> --output pkg.zip   # cookie backend

isolate, unisolate, restrict, and unrestrict require --comment. Every action asks for confirmation unless you pass --yes, and refuses to run non-interactively without it; declining the prompt exits 13. --dry-run is available on all actions except unisolate. In cookie mode, device IDs must be the 40-hex MachineId (or a hostname with exactly one match) and action IDs must be GUIDs; action-status needs --device the first time it sees an action on this machine.

Configuration

~/.xdr-cli/config.toml (created by xdr auth login, or by hand for the cookie quick start; set XDR_CLI_HOME to relocate the whole directory, e.g. one per tenant):

tenant_id = "…"                 # required for both backends
client_id = "…"                 # official backend only
auth_mode = "device_code"       # or "client_credentials" (see below)
client_secret = ""
api_backend = "auto"            # or "official" / "portal-cookie" to pin one
api_timeout = 120               # seconds; raise for heavy hunts
default_limit = 25              # incidents/alerts list when --limit is omitted
session_timeout_seconds = 1800  # automatic-session inactivity timeout
schema_stale_seconds = 86400    # cached schema is visibly stale after this age
schema_collection_stale_seconds = 604800  # nonblocking semantic-collection reminder
schema_collect_on_session_end = true  # master switch for session-end schema upkeep
schema_refresh_on_session_end = true  # refresh only if physical cache is missing/stale
schema_explore_on_session_end = true  # discover new locations after focused validation
schema_explore_max_queries = 5        # exploration queries per explicit session end (1-1000)
schema_maintenance_timeout_seconds = 90  # overall foreground upkeep deadline; maximum 3600

Unknown keys produce a warning on stderr.

Path	Purpose
`~/.xdr-cli/`	Config directory (`0700` on POSIX)
`~/.xdr-cli/config.toml`	Configuration (`0600`)
`~/.xdr-cli/token_cache.json`	MSAL token cache for the official backend (`0600`)
`~/.xdr-cli/portal_cookies.json`	Imported portal session cookie (`0600`)
`~/.xdr-cli/action_associations/`	Action ID → device ID pairs (IDs only) learned in cookie mode
`~/.xdr-cli/audit.log`	Local log of attempted state-changing commands (response actions, incident updates, auth changes, `lists init`, schema repair/import) and `investigate` runs. Written with redacted argv when the command is dispatched, before it runs, so `--dry-run` and declined attempts appear too; `--help` and argument errors do not, and outcomes are not recorded (`0600`)
`~/.xdr-cli/lists/*.txt`	Reference lists for library queries
`~/.xdr-cli/queries/*.kql`	Your own library queries (see docs/library.md)
`~/.xdr-cli/results/YYYY-MM-DD/`	Result artifacts and metadata
`~/.xdr-cli/schema/`, `sessions/`	Schema cache; session histories

Environment: XDR_CLI_HOME (config directory), XDR_SESSION (attach to a session), XDR_ACTOR (name parallel actors in one session), MDE_REFRESH_TOKEN (device timeline on the official backend, CI use).

Service-principal auth. Set auth_mode = "client_credentials" and client_secret in config.toml, and give the app registration application permissions with admin consent. The application names match the table above except Machine.Read.All (for Machine.Read) and AdvancedQuery.Read.All (for AdvancedQuery.Read). Tokens are acquired automatically; xdr auth login is not needed. xdr auth status reports main.authenticated from the cached delegated account, not from the service-principal credentials, so it can be false while app credentials work.