> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# detections command — run and manage detection configs

> Run ChainPatrol detection configs on demand, validate that they still return results, catch query drift, list suspected threats, and update a config.

```bash theme={null}
chainpatrol detections <healthcheck|validate|drift|run|list|configs>
```

Every subcommand is organization-scoped. Pass `--org <slug>` once and it is
[saved as your default](https://chainpatrol.com/docs/cli/installation.md#setting-a-default-organization).

## detections healthcheck

Run a health check across all of an organization's detection configs.

```bash theme={null}
chainpatrol detections healthcheck --org <slug> [options]
```

| Option | Description |
| - | - |
| `--org <slug>` | Organization slug. |
| `--source <key>` | Filter by detection source key. |
| `--min-results <n>` | Minimum recent results a config must have produced. |
| `--lookback-hours <n>` | Lookback window, in hours. |
| `--run` | Run the detection configs before validating them. |
| `--include-disabled` | Include disabled configs. |

```bash theme={null}
chainpatrol detections healthcheck --org acme --run
chainpatrol detections healthcheck --org acme --run --min-results 1 --lookback-hours 168
chainpatrol --json detections healthcheck --org acme --run
```

An unhealthy result exits with [code `6`](https://chainpatrol.com/docs/cli/output#exit-codes) — the check ran fine,
something is wrong. That makes it usable directly as a CI gate.

## detections validate

Validate that detection configs still produce the results you expect, without the
surrounding health report. Takes the same options as `healthcheck`.

```bash theme={null}
chainpatrol detections validate --org acme --source urlscan
chainpatrol detections validate --org acme --min-results 5
```

## detections drift

Surface drift signals — configs returning zero results, configs that have turned noisy,
and stale queries.

```bash theme={null}
chainpatrol detections drift --org <slug> [options]
```

| Option | Description |
| - | - |
| `--org <slug>` | Organization slug. |
| `--source <key>` | Filter by detection source key. |
| `--config-id <n>` | Filter by config ID. |
| `--lookback-hours <n>` | Lookback window, in hours. |
| `--include-disabled` | Include disabled configs. |

```bash theme={null}
chainpatrol detections drift --org acme --lookback-hours 168
chainpatrol detections drift --org acme --explain --output markdown
```

Add `--explain` to get the recommendation behind each signal rather than the counts alone.

## detections run

Run one or more detection configs on demand.

```bash theme={null}
chainpatrol detections run --org <slug> [options]
```

| Option | Description |
| - | - |
| `--org <slug>` | Organization slug. |
| `--config-id <n>` | Run a specific config. |
| `--source <key>` | Filter by detection source key. |
| `--include-disabled` | Include disabled configs. |
| `--dry-run` | Preview without executing. |

```bash theme={null}
chainpatrol detections run --org acme --source google_search
chainpatrol detections run --org acme --config-id 42
```

## detections list

List recent suspected threats (unconfirmed results from automated detection), with the same
filters as the app's Suspected Threats page.
Confidence comes back as a human-readable level rather than a raw score.

```bash theme={null}
chainpatrol detections list --org <slug> [filters]
```

| Option | Description |
| - | - |
| `--org <slug>` | Organization slug. |
| `--limit <n>` | Page size, 1–100. Defaults to 50. |
| `--cursor <n>` | Pagination cursor. |
| `--search <q>` | Search by threat content. |
| `--source <list>` | Comma list of detection source keys. |
| `--confidence <list>` | Comma list: `none`, `low`, `medium`, `high`. |
| `--asset-status <list>` | Comma list: `BLOCKED`, `ALLOWED`, `UNKNOWN`. |
| `--asset-type <list>` | Comma list of asset types. |
| `--brand <ids>` | Comma list of brand IDs. |
| `--liveness <list>` | Comma list: `ALIVE`, `DEAD`, `UNKNOWN`. |
| `--watchlist <list>` | Comma list: `ENABLED`, `DISABLED`. |
| `--reported <list>` | Comma list: `reported`, `not_reported`. |
| `--country-code <list>` | Comma list of 2-letter ISO country codes. |
| `--only-deleted` | Return only soft-deleted suspected threats. Without it, both deleted and non-deleted are returned. |
| `--exclude-deleted` | Leave soft-deleted suspected threats out, so totals match the app. Can't be combined with `--only-deleted`. |
| `--block-status <list>` | Comma list: `blocked`, `pending`. Both together select every confirmed threat, including **Pending Blocked** ones for organizations without active protection. |
| `--min-score <n>` | Only suspected threats with a raw score of at least `n` (0–1). Use this rather than `--confidence` for a fixed cut-off such as `0.8`. |
| `--max-score <n>` | Only suspected threats with a raw score of at most `n` (0–1). |
| `--include-total` | Also print how many suspected threats match across all pages. |
| `--from <iso>` / `--to <iso>` | Date range (ISO 8601) on when the suspected threat was created. Leave both out for every suspected threat. |

Each row shows the confidence and raw score. Pending blocks are shown as `PENDING_BLOCKED`
rather than `UNKNOWN`.

```bash theme={null}
chainpatrol detections list --org acme --confidence medium,high
chainpatrol detections list --org acme --source twitter --liveness ALIVE
chainpatrol detections list --org acme --reported not_reported --watchlist ENABLED
chainpatrol detections list --org acme --brand 12,34 --country-code US,GB
chainpatrol detections list --org acme --min-score 0.8 --include-total
chainpatrol detections list --org acme --block-status blocked,pending --include-total
```

See [Evaluating suspected threats](https://chainpatrol.com/docs/external-api/evaluating-detections.md) for the usual counting
questions.

## configs list

List the detection configs available to your organization. `chainpatrol configs list` is a
top-level shorthand for `chainpatrol detections configs list`.

```bash theme={null}
chainpatrol configs list --org acme
chainpatrol detections configs list --org acme
chainpatrol --json configs list --org acme
```

## detections configs update

Update an existing config's status, title, cron schedule, or query.

```bash theme={null}
chainpatrol detections configs update --org <slug> --config-id <n> [options]
```

| Option | Description |
| - | - |
| `--org <slug>` | Organization slug. |
| `--config-id <n>` | Config ID. Required. |
| `--enable` / `--disable` | Enable or disable the config. |
| `--title <text>` | New title. |
| `--description <text>` | New description. |
| `--cron <expr>` | New CRON expression. |
| `--set key=value` | Patch a value inside the config. Repeatable. |
| `--merge-config` | Merge `--set` keys into the existing config. Defaults to true. |
| `--dry-run` | Preview without applying. |

`--set` values are parsed: `true`, `false`, `null`, and numbers become their JSON types,
`{...}` and `[...]` are parsed as JSON, and everything else stays a string.

```bash theme={null}
chainpatrol detections configs update --org acme --config-id 42 --disable
chainpatrol detections configs update --org acme --config-id 42 \
  --set query=brand-phishing --set maxResults=100
chainpatrol detections configs update --org acme --config-id 42 \
  --set query="phishing site" --dry-run --output json
```

`detections configs run` is also accepted, and behaves the same as `detections run`.

## Related

* [`GET /organization/detections`](https://chainpatrol.com/docs/external-api/detection-list)
* [`GET /organization/detection-configs`](https://chainpatrol.com/docs/external-api/detection-configs-list)
* [`POST /organization/detection-configs/{id}`](https://chainpatrol.com/docs/external-api/detection-configs-update)
* [Suspected threats concept](https://chainpatrol.com/docs/concepts/detections.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.