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

# lua preprocessors and lua postprocessors

> List, deploy, activate, deactivate, and delete the processors that run before and after the model

`lua preprocessors` manages the [preprocessors](/concepts/processors) that run on every incoming message before the model sees it; `lua postprocessors` manages the postprocessors that run on every response before it is sent. The two commands take the same actions and differ only in the flag names. `deploy`, `activate`, `deactivate`, and `delete` change what every end user's messages pass through as soon as they succeed.

*Verified against lua-cli 3.33.0. The `Priority:` line in `view` output needs lua-cli 3.40.0 or later.*

## Synopsis

<Tabs>
  <Tab title="Preprocessors">
    ```bash theme={null}
    lua preprocessors [view|versions|deploy|activate|deactivate|delete] [--preprocessor-name <name>] [--preprocessor-version <ver>|latest]
    ```
  </Tab>

  <Tab title="Postprocessors">
    ```bash theme={null}
    lua postprocessors [view|versions|deploy|activate|deactivate|delete] [--postprocessor-name <name>] [--postprocessor-version <ver>|latest]
    ```
  </Tab>
</Tabs>

## Description

With no action either command opens a menu covering every action. Every action runs against production.

`view` lists the processors of that kind in `lua.skill.yaml` with their ID, their `priority` (lower runs first; `100` when the processor sets none; see [About processors](/concepts/processors)), whether a version is deployed, and when.

`versions` prints a pointer to [`lua version list`](/reference/cli/version): per-primitive history is managed by [agent versions](/concepts/releases-and-versions).

`deploy` makes one pushed version live without a confirmation prompt. It is the same operation as `lua deploy preprocessor --name <name> --set-version <ver> --force` (or `lua deploy postprocessor …`); [`lua deploy`](/reference/cli/deploy) also records the deployed version in `lua.skill.yaml` and reports the agent version it promoted.

`activate` and `deactivate` turn the processor on or off without changing its version. A deactivated preprocessor no longer sees incoming messages; a deactivated postprocessor no longer sees responses.

`delete` removes the processor from the server. A processor that has pushed versions is deactivated instead of deleted and stays in `lua.skill.yaml` until you remove it. `delete` also resolves processors that exist only on the server.

The name flag matches the processor name or its ID. Every form needs a project directory and a credential.

There is no `lua pre` or `lua pp` command. Those spellings are accepted only where a primitive type is expected: `pre`, `preproc`, `preprocessors` → `preprocessor` and `pp`, `post`, `postproc`, `postprocessors` → `postprocessor` for [`lua push`](/reference/cli/push); `pre`, `preprocessors` and `pp`, `post`, `postprocessors` for [`lua deploy`](/reference/cli/deploy), [`lua test`](/reference/cli/test), and `lua logs --type`.

## Arguments

| Argument | Values | Description |
| - | - | - |
| `action` | `view`, `versions`, `deploy`, `activate`, `deactivate`, `delete` | Omit it to open the menu. |

Accepted spellings, both commands: `show`, `info` → `view`; `list-versions` → `versions`; `publish` → `deploy`; `on`, `enable` → `activate`; `off`, `disable` → `deactivate`; `rm`, `remove`, `del` → `delete`.

## Options

| Option | Description | Default |
| - | - | - |
| `--preprocessor-name <name>` | Preprocessor name or ID. Required for every `lua preprocessors` action except `view`. | — |
| `--preprocessor-version <ver>` | Version to deploy, or `latest`. Required for `lua preprocessors deploy`. | — |
| `--postprocessor-name <name>` | Postprocessor name or ID. Required for every `lua postprocessors` action except `view`. | — |
| `--postprocessor-version <ver>` | Version to deploy, or `latest`. Required for `lua postprocessors deploy`. | — |
| `--ci` | Global flag. Refuse any prompt with exit `1` instead of waiting for input. | off |

## Examples

List the preprocessors with their priority and whether each is deployed.

```bash theme={null}
lua preprocessors view
```

```text Output theme={null}
============================================================
⚙️  Production PreProcessors
============================================================

📥 pii-redaction
   PreProcessor ID: preprocessor_7d8daed7-c2ab-4c92-8042-c16ee15340a3
   Priority: 10
   Deployed ⭐
   Deployed: 12/09/2026, 13:49:46

============================================================
```

List the postprocessors the same way.

```bash theme={null}
lua postprocessors view
```

```text Output theme={null}
============================================================
⚙️  Production PostProcessors
============================================================

📤 ticket-footer
   PostProcessor ID: postprocessor_d39f9879-b73b-4a71-9032-40eeab2ad429
   Priority: 100
   Deployed ⭐
   Deployed: 12/09/2026, 13:49:47

============================================================
```

Make the newest pushed preprocessor version live from CI.

```bash theme={null}
lua preprocessors deploy --preprocessor-name pii-redaction --preprocessor-version latest --ci
```

Take a postprocessor out of the response path without deleting it.

```bash theme={null}
lua postprocessors deactivate --postprocessor-name ticket-footer --ci
```

Check what a processor did to real traffic.

```bash theme={null}
lua logs --type preprocessor --name pii-redaction --limit 10
```

## Exit codes

| Code | Meaning | When |
| - | - | - |
| `0` | OK | The action completed, including a `delete` that deactivated instead. |
| `1` | Error | The server refused the action, the version flag names a version that does not exist, or a prompt was needed under `--ci`. |
| `2` | Usage | Unknown action, or the required name or version flag is missing. |
| `3` | Not found | The processor is not in `lua.skill.yaml` (nor on the server, for `delete`), or it has no pushed versions to deploy. |
| `9` | Auth | No valid credential. |
| `10` | Forbidden | The credential cannot manage this agent. |
| `11` | Unavailable | Network error or a server 5xx. |

The full table is in [Errors and exit codes](/reference/cli/errors-and-exit-codes).

## See also

* [`PreProcessor`](/reference/sdk/preprocessor) and [`PostProcessor`](/reference/sdk/postprocessor) — the SDK types
* [Add a processor](/build/add-a-processor)
* [About processors](/concepts/processors) — order, priority, block and proceed, fail-open and fail-closed
* [`lua deploy`](/reference/cli/deploy) — the same deploy with the agent version reported
* [`lua logs`](/reference/cli/logs) — `--type preprocessor` and `--type postprocessor`


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