> ## 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.*

## 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, 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 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
   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
   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`