# Guardrails Commands

> See [Guardrails module docs](../../modules/guardrails) for permissions and data model.

# Guardrails Commands

See [Guardrails module docs](../../modules/guardrails) for permissions and data model.

### `soat create-guardrail`

Create a guardrail

- Method: `POST`
- Path: `/api/v1/guardrails`

#### Usage

```bash
soat create-guardrail --name <string> --document <object<string, unknown>>
```

#### Options

##### `--project-id`

Public ID of the project

- Source: `body`
- Required: no
- Type: `string`

##### `--name`

Human-readable name

- Source: `body`
- Required: yes
- Type: `string`
- Example: `Budget Update Guardrail`

##### `--description`

—

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--document`

The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `runtime.*` namespaces. 

- Source: `body`
- Required: yes
- Type: `object<string, unknown>`

##### `--context-tool-id`

—

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--context-mode`

—

- Source: `body`
- Required: no
- Type: `enum("merge", "replace")`

##### `--version-label`

Optional tag for the config version this write archives (e.g. `initial`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change.

- Source: `body`
- Required: no
- Type: `string`
- Example: `initial`

### `soat list-guardrails`

List guardrails

- Method: `GET`
- Path: `/api/v1/guardrails`

#### Usage

```bash
soat list-guardrails
```

#### Options

##### `--project-id`

Project public ID to filter by

- Source: `query`
- Required: no
- Type: `string`

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat get-guardrail`

Get a guardrail

- Method: `GET`
- Path: `/api/v1/guardrails/{guardrail_id}`

#### Usage

```bash
soat get-guardrail --guardrail-id <string>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

### `soat update-guardrail`

Update a guardrail

- Method: `PATCH`
- Path: `/api/v1/guardrails/{guardrail_id}`

#### Usage

```bash
soat update-guardrail --guardrail-id <string>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

##### `--name`

—

- Source: `body`
- Required: no
- Type: `string`

##### `--description`

—

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--document`

The action-class document. `class` maps a call to an action class; `guard` gates class-B autonomy. Both are single JSON Logic expressions over the `args.*` / `context.*` / `runtime.*` namespaces. 

- Source: `body`
- Required: no
- Type: `object<string, unknown>`

##### `--context-tool-id`

—

- Source: `body`
- Required: no
- Type: `string \| null`

##### `--context-mode`

—

- Source: `body`
- Required: no
- Type: `enum("merge", "replace", null)`

##### `--version-label`

Optional tag for the config version this write archives (e.g. `pre-tightening`). Annotates the version only — it is not stored on the guardrail and is not part of the config, so labelling a change is never itself a change. Ignored when the write changes no policy, since no version is created.

- Source: `body`
- Required: no
- Type: `string`
- Example: `pre-tightening`

### `soat delete-guardrail`

Delete a guardrail

- Method: `DELETE`
- Path: `/api/v1/guardrails/{guardrail_id}`

#### Usage

```bash
soat delete-guardrail --guardrail-id <string>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

### `soat list-guardrail-versions`

List a guardrail's config versions

- Method: `GET`
- Path: `/api/v1/guardrails/{guardrail_id}/versions`

#### Usage

```bash
soat list-guardrail-versions --guardrail-id <string>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

##### `--limit`

Maximum number of results to return

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

Number of results to skip

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat get-guardrail-version`

Fetch an archived guardrail version

- Method: `GET`
- Path: `/api/v1/guardrails/{guardrail_id}/versions/{version}`

#### Usage

```bash
soat get-guardrail-version --guardrail-id <string> --version <integer>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

##### `--version`

—

- Source: `path`
- Required: yes
- Type: `integer`

### `soat restore-guardrail-version`

Restore an archived guardrail config

- Method: `POST`
- Path: `/api/v1/guardrails/{guardrail_id}/versions/{version}/restore`

#### Usage

```bash
soat restore-guardrail-version --guardrail-id <string> --version <integer>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

##### `--version`

—

- Source: `path`
- Required: yes
- Type: `integer`

##### `--label`

Optional tag for the version the restore creates. Defaults to `restored from v<version>`.

- Source: `body`
- Required: no
- Type: `string`
- Example: `rollback to pre-incident policy`

### `soat evaluate-guardrail`

Dry-run evaluate a guardrail

- Method: `POST`
- Path: `/api/v1/guardrails/{guardrail_id}/evaluate`

#### Usage

```bash
soat evaluate-guardrail --guardrail-id <string>
```

#### Options

##### `--guardrail-id`

—

- Source: `path`
- Required: yes
- Type: `string`

##### `--args`

The proposed call's arguments (the `args.*` namespace).

- Source: `body`
- Required: no
- Type: `object<string, unknown>`

##### `--guardrail-context`

The caller-supplied guardrail context (the `context.*` namespace), combined with the context tool per `context_mode`. 

- Source: `body`
- Required: no
- Type: `object<string, unknown>`

##### `--tool-id`

Optional tool to resolve `runtime.tool.*` against.

- Source: `body`
- Required: no
- Type: `string`