> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/guardrails.md).

# guardrails

Safety and compliance checks (`adaptorType: GuardrailImport`) that validate data flowing through integrations — PII detection, content moderation, and custom AI-based evaluation. Unlike [`ai-agents`](/cli/commands/ai-agents.md), which produce content with LLMs, guardrails screen content: they flag, reject, or mask records that violate policy.

**REST API**: Guardrails are a specialized import adaptor (`GuardrailImport`). Schemas live in the imports spec — see the `Guardrail` and `GuardrailImport` components. The CLI filters and auto-tags `/v1/imports` so every call targets a guardrail-shaped record.

```
celigo guardrails <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## Subcommands

| Subcommand                                  | Purpose                                                                                               |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `list`                                      | List all guardrail imports in the account.                                                            |
| `get <id>`                                  | Fetch one guardrail by ID.                                                                            |
| `create`                                    | Create a guardrail from JSON on stdin (`adaptorType` auto-set).                                       |
| `update <id>`                               | Full replace from stdin (destructive `PUT`).                                                          |
| `set <id> key=value …`                      | Safe field edit: `GET` → modify → `PUT`.                                                              |
| `delete <id>`                               | Delete a guardrail.                                                                                   |
| `invoke [id]`                               | Invoke a saved guardrail against piped records, or preview a piped guardrail doc when no id is given. |
| `enable-debug <id>`                         | Enable debug logging via `PATCH` on `debugUntil`.                                                     |
| `disable-debug <id>`                        | Clear `debugUntil`.                                                                                   |
| `clone <id>`                                | Clone the guardrail (same-env or cross-env).                                                          |
| `replace-connection <id> <newConnectionId>` | Replace the underlying connection (BYOK `ai_agent` guardrails only).                                  |

***

## `celigo guardrails list`

List every guardrail import in the account. The CLI fetches `/v1/imports` and filters client-side to rows where `adaptorType === "GuardrailImport"`.

**Signature**

```bash
celigo guardrails list
```

**Arguments**

None.

**Flags**

None beyond the [global flags](/cli/getting-started/global-flags.md) (`--format`, `--jq`, `--profile`, `--verbose`).

**Example**

```bash
celigo guardrails list --format table
```

**Corresponds to**: [`GET /v1/imports`](https://developer.celigo.com/api/api-reference/imports#get-v1-imports) (client-side filter on `adaptorType`)

***

## `celigo guardrails get`

Fetch a single guardrail import by ID.

**Signature**

```bash
celigo guardrails get <id>
```

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `<id>`   | string | Yes      | Guardrail import `_id`. |

**Example**

```bash
celigo guardrails get 65f1a7b2c3d4e5f6a7b8c9d0
```

**Corresponds to**: [`GET /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#get-v1-imports-_id)

***

## `celigo guardrails create`

Create a guardrail import from a JSON body on stdin. The CLI forces `adaptorType = "GuardrailImport"` before posting, so you don't need to include it in the payload.

**Signature**

```bash
celigo guardrails create
```

**Arguments**

None. Reads JSON on stdin.

**Request body**

See the `Guardrail` and `GuardrailImport` schemas for the full payload shape (type, confidence threshold, and the `pii` / `moderation` / `aiAgent` sub-configurations). Key fields:

* `guardrail.type` — one of `pii`, `moderation`, `ai_agent`.
* `guardrail.confidenceThreshold` — detection threshold (0–1, default `0.7`).
* `guardrail.pii.entities[]` / `.mask` — required for `pii`.
* `guardrail.moderation.categories[]` — required for `moderation`.
* `guardrail.aiAgent` — required for `ai_agent`; same shape as an `agents` config, including optional `_connectionId` for BYOK.

**Example**

```bash
celigo guardrails create < guardrail.json
```

**Corresponds to**: [`POST /v1/imports`](https://developer.celigo.com/api/api-reference/imports#post-v1-imports) (with `adaptorType=GuardrailImport` injected)

***

## `celigo guardrails update`

Replace a guardrail import with the JSON body on stdin. Destructive — any field omitted from the payload is erased. Prefer `set` for targeted edits.

> ⚠️ **`PUT` fully replaces the guardrail.** Any field omitted from the payload is erased. Prefer `set` for targeted edits, or `get | jq | update` to preserve the rest of the document.

**Signature**

```bash
celigo guardrails update <id>
```

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `<id>`   | string | Yes      | Guardrail import `_id`. |

**Request body**

The complete guardrail document. See the `GuardrailImport` schema.

**Example**

```bash
celigo guardrails get 65f1a7b2c3d4e5f6a7b8c9d0 \
  | jq '.guardrail.confidenceThreshold = 0.85' \
  | celigo guardrails update 65f1a7b2c3d4e5f6a7b8c9d0
```

**Corresponds to**: [`PUT /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#put-v1-imports-_id)

***

## `celigo guardrails set`

Safe field edit: `GET` → apply one or more `key=value` assignments → `PUT` the full object back.

**Signature**

```bash
celigo guardrails set <id> <assignments...>
```

**Arguments**

| Argument           | Type   | Required | Description                                                                                                                                                                          |
| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<id>`             | string | Yes      | Guardrail import `_id`.                                                                                                                                                              |
| `<assignments...>` | string | Yes (≥1) | One or more `key=value` pairs. Values are JSON-parsed (`disabled=false` → boolean). Dot + bracket notation supported (e.g. `guardrail.pii.mask=true`). `key=null` removes the field. |

**Example**

```bash
celigo guardrails set 65f1a7b2c3d4e5f6a7b8c9d0 \
  name="Block PII in support messages" \
  guardrail.confidenceThreshold=0.9
```

**Corresponds to**: [`GET /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#get-v1-imports-_id) then [`PUT /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#put-v1-imports-_id)

***

## `celigo guardrails delete`

Delete a guardrail import by ID. Prompts for confirmation unless `-y` is passed.

> ⚠️ **Deleting a guardrail is destructive.** Any flow or tool that references it loses the guardrail step. Confirm it is unused before deleting.

**Signature**

```bash
celigo guardrails delete <id> [flags]
```

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `<id>`   | string | Yes      | Guardrail import `_id`. |

**Flags**

| Flag          | Type    | Default | Description                               |
| ------------- | ------- | ------- | ----------------------------------------- |
| `-y`, `--yes` | boolean | `false` | Skip the interactive confirmation prompt. |

**Example**

```bash
celigo guardrails delete 65f1a7b2c3d4e5f6a7b8c9d0 -y
```

**Corresponds to**: [`DELETE /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#delete-v1-imports-_id)

***

## `celigo guardrails invoke [id]`

Run a guardrail without creating a job. Two modes:

* **With `<id>`** — invoke a *saved* guardrail against records piped on stdin; the response is the guardrail's evaluation for each record (`POST /v1/imports/{_id}/invoke`).
* **Without `<id>`** — pipe a *guardrail document* on stdin to preview its evaluation without saving (`POST /v1/imports/preview`; the CLI sets `adaptorType: GuardrailImport`). Stdin is required in this mode.

**Signature**

```bash
celigo guardrails invoke [id]
```

**Arguments**

| Argument | Type   | Required | Description                                                         |
| -------- | ------ | -------- | ------------------------------------------------------------------- |
| `[id]`   | string | No       | Guardrail import `_id`. Omit to preview a piped guardrail document. |

**Examples**

```bash
# Invoke a saved guardrail against records
echo '[{"message":"Contact me at jdoe@example.com or 555-1212"}]' \
  | celigo guardrails invoke 65f1a7b2c3d4e5f6a7b8c9d0

# Preview an unsaved guardrail document
celigo guardrails invoke < guardrail.json
```

**Corresponds to**: [`POST /v1/imports/{_id}/invoke`](https://developer.celigo.com/api/api-reference/imports#post-v1-imports-_id-invoke) (with `id`) or `POST /v1/imports/preview` (without).

***

## `celigo guardrails enable-debug`

Enable debug logging on a guardrail by setting `debugUntil` via `PATCH`. Debug windows are capped at 60 minutes.

**Signature**

```bash
celigo guardrails enable-debug <id> [flags]
```

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `<id>`   | string | Yes      | Guardrail import `_id`. |

**Flags**

| Flag                   | Type   | Default | Description                              |
| ---------------------- | ------ | ------- | ---------------------------------------- |
| `--duration <minutes>` | number | `60`    | Debug duration in minutes. Capped at 60. |

**Example**

```bash
celigo guardrails enable-debug 65f1a7b2c3d4e5f6a7b8c9d0 --duration 30
```

**Corresponds to**: [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#patch-v1-imports-_id) (JSON Patch: `replace /debugUntil`)

***

## `celigo guardrails disable-debug`

Clear `debugUntil` on a guardrail import, stopping debug log collection.

**Signature**

```bash
celigo guardrails disable-debug <id>
```

**Arguments**

| Argument | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `<id>`   | string | Yes      | Guardrail import `_id`. |

**Example**

```bash
celigo guardrails disable-debug 65f1a7b2c3d4e5f6a7b8c9d0
```

**Corresponds to**: [`PATCH /v1/imports/{_id}`](https://developer.celigo.com/api/api-reference/imports#patch-v1-imports-_id) (JSON Patch: `remove /debugUntil`)

***

## `celigo guardrails clone`

Clone a guardrail import. Two modes:

* **Same-env clone** — no stdin. The CLI reads the source guardrail, builds a self-map from its `_connectionId` (empty map for non-BYOK guardrails, since `pii` and `moderation` types don't require a connection), and submits the clone.
* **Cross-env clone** — pipe JSON on stdin with a `connectionMap` that maps source connection IDs to target connection IDs: `{"connectionMap":{"sourceConnId":"targetConnId"},"name":"..."}`.

**Signature**

```bash
celigo guardrails clone <id> [flags]
```

**Arguments**

| Argument | Type   | Required | Description                    |
| -------- | ------ | -------- | ------------------------------ |
| `<id>`   | string | Yes      | Source guardrail import `_id`. |

**Flags**

| Flag            | Type   | Default                   | Description                                           |
| --------------- | ------ | ------------------------- | ----------------------------------------------------- |
| `--name <name>` | string | `"Clone - <source name>"` | Name for the cloned guardrail. Defaults match the UI. |

**Example**

```bash
# Same-env clone
celigo guardrails clone 65f1a7b2c3d4e5f6a7b8c9d0 --name "Copy of PII blocker"

# Cross-env clone (BYOK ai_agent guardrail)
echo '{"connectionMap":{"63abc...":"71xyz..."},"name":"PII blocker (prod)"}' \
  | celigo guardrails clone 65f1a7b2c3d4e5f6a7b8c9d0
```

**Corresponds to**: [`POST /v1/imports/{_id}/clone`](https://developer.celigo.com/api/api-reference/imports#post-v1-imports-_id-clone)

***

## `celigo guardrails replace-connection`

Replace the connection referenced by a guardrail — only meaningful for `ai_agent` guardrails with a BYOK `_connectionId`. `pii` and `moderation` guardrails don't carry a connection.

**Signature**

```bash
celigo guardrails replace-connection <id> <newConnectionId>
```

**Arguments**

| Argument            | Type   | Required | Description                         |
| ------------------- | ------ | -------- | ----------------------------------- |
| `<id>`              | string | Yes      | Guardrail import `_id`.             |
| `<newConnectionId>` | string | Yes      | The replacement connection's `_id`. |

**Example**

```bash
celigo guardrails replace-connection 65f1a7b2c3d4e5f6a7b8c9d0 71xyz456...
```

**Corresponds to**: [`PUT /v1/imports/{_id}/replaceConnection`](https://developer.celigo.com/api/api-reference/imports#put-v1-imports-_id-replaceconnection)

***

## Gotchas

* **Three guardrail types, three required sub-configs.** `guardrail.type = "pii"` needs `guardrail.pii.entities[]` with at least one entity. `type = "moderation"` needs `guardrail.moderation.categories[]` with at least one category. `type = "ai_agent"` needs `guardrail.aiAgent` (same shape as `agents`).
* **PII detection example entities**: `email_address`, `phone_number`, `us_social_security_number`, `credit_card_number`, `persons_name`, `ip_address`, and a long list of country-specific IDs. See the `Guardrail.pii.entities` enum for the full list.
* **Moderation categories** cover `hate`, `harassment`, `self_harm`, `sexual`, `violence`, `illicit`, and their intensified variants (`*_threatening`, `*_graphic`, `*_minors`, etc.). Pick only what you intend to enforce — every category adds latency.
* **`confidenceThreshold` defaults to `0.7`.** Lower values catch more potential issues but raise false positives; raise it when you're seeing noisy flags on benign records.
* **No `_connectionId` required for `pii` or `moderation`.** The guardrail runs inside Celigo. Only `ai_agent` guardrails may carry a BYOK `_connectionId`; use `replace-connection` to swap it.
* **`pii.mask: true` rewrites the record** on its way out — callers see redacted values instead of the raw input. `mask: false` only flags detections without modifying the record.
* **`invoke` doesn't create a job.** Evaluations are ephemeral; use `enable-debug` + the `imports debug-requests` flow (since guardrails are imports) to capture runs inside flows.
* **API path is `/v1/imports`, not `/v1/guardrails`.** The CLI command is its own namespace, but every request is on the shared imports endpoint with `adaptorType=GuardrailImport` as the discriminator.

## Related

* [ai-agents](/cli/commands/ai-agents.md) — LLM-powered import steps that generate or transform content. Guardrails screen; agents produce.
* [tools](/cli/commands/tools.md) — reusable building blocks that can embed guardrail steps alongside exports, imports, and lookups.
* [mcp-servers](/cli/commands/mcp-servers.md) — expose tools (and, transitively, guardrail-protected steps) to MCP clients.
* [imports](/cli/commands/imports.md) — the parent resource type. Generic import commands also work on guardrail IDs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/guardrails.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.