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

# plerion custom-checks

> Create, update, list, delete, and dry run custom checks.

With **plerion custom-checks**, you can manage your own Rego checks and try a check against live assets before you save it.

***

## Synopsis

```bash theme={"system"}
plerion custom-checks <subcommand> [options]
```

***

## Subcommands

### list

```bash theme={"system"}
plerion custom-checks list [--asset-type <type>] [--scope <scope>] [--per-page N] [--all]
```

| Option | Type | Description |
| - | - | - |
| `--asset-type` | string | Only checks that target this asset type (e.g. `AWS::S3::Bucket`) |
| `--scope` | string | Only checks with this target scope: `batch` or `all` |
| `--per-page` | number | Checks per page, from 1 to 200 (default: 50) |
| `--all` | flag | Fetch all pages automatically |

### get

```bash theme={"system"}
plerion custom-checks get --id <id>
```

### create

```bash theme={"system"}
plerion custom-checks create --file <path>
```

Creates a check from a JSON definition. Pass `-` as the path to read from stdin.

| Option | Type | Description |
| - | - | - |
| `--file` | string | **(required)** JSON file with the check definition, or `-` for stdin |

### update

```bash theme={"system"}
plerion custom-checks update --id <id> --file <path>
```

Replaces the check in full with the definition in the file. Each update increments the check's version.

| Option | Type | Description |
| - | - | - |
| `--id` | string | **(required)** Custom check ID |
| `--file` | string | **(required)** JSON file with the full check definition, or `-` for stdin |

### delete

```bash theme={"system"}
plerion custom-checks delete --id <id>
```

The check is removed immediately. Findings it produced are cleaned up in the background.

### dry-run

```bash theme={"system"}
plerion custom-checks dry-run --integration-id <id> --file <path>
```

Runs a check against the assets of one integration without saving findings. The check doesn't need to be saved first, so you can test an edit before running `update`. Returns a dry run ID.

| Option | Type | Description |
| - | - | - |
| `--integration-id` | string | **(required)** Integration whose assets the check runs against |
| `--file` | string | **(required)** JSON file with the check to run, or `-` for stdin. Needs `customCheckId`, `target`, and `body` |

### dry-run-status

```bash theme={"system"}
plerion custom-checks dry-run-status --id <dry-run-id>
```

Returns the status of a dry run: `RUNNING`, `SUCCEEDED`, `FAILED`, `TIMED_OUT`, or `ABORTED`. The table shows the status and the number of findings. Use `--output json` to see the preview findings once the run completes.

***

## Check definition

`create`, `update`, and `dry-run` read the check as a JSON object.

| Field | Required | Description |
| - | - | - |
| `slug` | yes | Lowercase letters, digits, and hyphens, up to 128 characters |
| `title` | yes | Up to 256 characters |
| `description` | no | Up to 4,096 characters |
| `target.assetType` | yes | Asset type the check evaluates (e.g. `AWS::S3::Bucket`) |
| `target.scope` | yes | `all` evaluates every asset of the type at once; `batch` evaluates them in chunks |
| `additionalAssets` | no | Other asset types the check reads, as `[{"assetType": "..."}]` |
| `defaults.severityLevel` | yes | `INFORMATIONAL`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` |
| `defaults.message` | yes | Message shown on findings the check produces |
| `defaults.informational` | yes | `true` or `false` |
| `defaults.remediation` | no | Remediation guidance, up to 4,096 characters |
| `type` | yes | `rego` |
| `body` | yes | The Rego policy |

<Tip>
  The JSON from `get --output json` can be edited and sent straight back. The CLI drops the fields Plerion sets itself (such as `version`, `createdAt`, and `updatedBy`) before sending. For `create` and `update` it also drops `customCheckId`, which `dry-run` keeps to label its results.
</Tip>

***

## Examples

```bash theme={"system"}
# List all custom checks
plerion custom-checks list --all

# Checks that target S3 buckets
plerion custom-checks list --asset-type AWS::S3::Bucket

# Create a check from a file
plerion custom-checks create --file s3-check.json

# Edit a check and save it back
plerion custom-checks get --id 3f2c1a9e-8b7d-4c21-9e8f-2a6b4d10c7f3 --output json > check.json
plerion custom-checks update --id 3f2c1a9e-8b7d-4c21-9e8f-2a6b4d10c7f3 --file check.json

# Try the edited check against one integration, then poll for the results
plerion custom-checks dry-run --integration-id 458511a1-9bc2-4fce-97a0-0e3139588e6e --file check.json
plerion custom-checks dry-run-status --id 2ea262bd-aa14-48c2-81ce-fa783cca7227 --output json

# Delete a check
plerion custom-checks delete --id 3f2c1a9e-8b7d-4c21-9e8f-2a6b4d10c7f3
```

***

## Output columns

| Column | Description |
| - | - |
| ID | Custom check ID |
| SLUG | Check slug |
| TITLE | Check title |
| ASSET TYPE | Asset type the check targets |
| SCOPE | Target scope (`batch` or `all`) |
| SEVERITY | Default severity level |
| VERSION | Check version |
| UPDATED BY | User who last updated the check |
| UPDATED AT | Update timestamp |

### Dry run output columns

| Column | Description |
| - | - |
| DRY RUN ID | Dry run ID |
| STATUS | Dry run status |
| POLL URL | API path for the dry run's status (`dry-run` only) |
| STARTED AT | Start timestamp (`dry-run-status` only) |
| COMPLETED AT | Completion timestamp (`dry-run-status` only) |
| FINDINGS | Number of preview findings (`dry-run-status` only) |


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