The td CLI.
A single static binary that wraps the whole platform — the fastest path for operators, on-call, and CI. It speaks human at the terminal and JSON to your scripts, with predictable exit codes for everything in between.
Install
Install with Homebrew, the one-line script, or by dropping the static binary on PATH. No runtime to manage.
SHELLinstall $ brew install threatdefendr/tap/td # macOS . Linuxbrew $ curl -fsSL https://td.sh/install | sh # everywhere else $ td --version td 2026.06.20 (build a4f1c2e)
Authenticate
At a terminal, td auth login completes SSO in the browser and writes a token to ~/.config/td. In CI, set TD_TOKEN to a scoped service token instead.
SHELLlogin $ td auth login # opens browser, SSO via your IdP ok logged in as alex@acme.io . workspace acme-prod # non-interactive (CI) $ export TD_TOKEN=tds_live_xxxxxxxx $ td auth whoami --output json
Core commands
Commands are grouped by surface; each group mirrors an area of the platform. The everyday set:
SHELLthe daily five $ td events tail --severity=high $ td detect deploy ./detections/ $ td case open --severity=HIGH --title="oncall handoff" $ td contain isolate-host --id=h_47193 $ td adversary show IRONVEIL --iocs
| Group | What it covers |
|---|---|
events | Tail and search the fabric |
detect | Lint, test, back-test, deploy, roll back detections |
case | Open, list, assign, and close cases |
contain | Isolate, disable, revoke, block — and reverse |
connector | Deploy and health-check data sources |
webhooks | Create endpoints and rotate signing secrets |
Scripting
Every command takes --output json for machine-readable output, and returns a specific exit code so a pipeline can branch on the failure mode rather than parsing stderr.
SHELLjson + jq + exit codes # live detections, slowest evaluation first $ td detect ls --output json \ | jq -r '.[] | select(.state=="LIVE") | [.eval_p50, .id] | @tsv' \ | sort -rn # exit codes: 0 ok . 1 error . 2 usage . 4 auth . 8 rate-limited $ td events tail --severity=high || echo "exited $?"
--output json is part of the API contract and versioned with it — safe to depend on in automation, unlike the human-formatted table, which we reserve the right to prettify.Config & profiles
Settings live in ~/.config/td/config.toml. Switch workspaces, or keep separate profiles — one for prod, one for IR — and select a profile per command.
SHELLworkspaces + profiles $ td config get workspace acme-prod $ td workspace use acme-staging # change the default workspace $ td --profile ir case ls --open # run one command under a profile
Where to go next
- Quickstart — zero to a live detection with the CLI.
- Detection-as-code — the CLI in a CI pipeline.
- SDK overview — feature parity across runtimes.