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

# bt preprocessors

> Bootstrap, preview, and push trace preprocessors from local TypeScript or JavaScript files, and manage published preprocessors from the CLI.

`bt preprocessors` manages [preprocessors](/docs/observe/topics/enable#write-a-custom-preprocessor) defined in local TypeScript or JavaScript files. A preprocessor turns a trace into the messages that prompt-based scorers receive for [trace template variables](/docs/evaluate/llm-as-a-judge#score-traces) such as `{{preprocessed}}`. Use the CLI to scaffold a starter file, run it against a real trace, and publish it to a project without using the preprocessor editor.

<Note>
  `bt` v0.26.0 or later is required. `bt preprocessors push` and `bt preprocessors preview` require Node.js. The `braintrust/preprocessors` helper is embedded in the CLI, so install the Braintrust TypeScript SDK v3.36.0 or later only if you want editor types and typechecking.
</Note>

## Subcommands

| Subcommand | Description |
| - | - |
| `bt preprocessors push <PATH>` | Push local preprocessor definitions to Braintrust |
| `bt preprocessors bootstrap <NAME>` | Create a starter preprocessor file |
| `bt preprocessors preview <PATH>` | Run a local preprocessor on a trace and print the result |
| `bt preprocessors list` | List preprocessors in the current project. Running `bt preprocessors` with no subcommand does the same. |
| `bt preprocessors view [slug]` | View a preprocessor's details |
| `bt preprocessors invoke [slug]` | Invoke a published preprocessor |
| `bt preprocessors delete [slug]` | Delete a preprocessor |

`list`, `view`, `invoke`, and `delete` are aliases for [`bt functions`](/docs/reference/cli/functions) scoped to preprocessors and accept the same flags.

## Write a preprocessor

Export each definition with `customPreprocessor()` from `braintrust/preprocessors`. Named and default exports are supported, and a file can export more than one definition.

```typescript conversation.preprocessor.ts theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { customPreprocessor } from "braintrust/preprocessors";

export const conversation = customPreprocessor(
  { name: "Conversation", slug: "conversation" },
  (span) => {
    if (span.span_attributes?.type === "score") return null;
    return typeof span.output === "string" ? span.output : null;
  },
);
```

The handler runs once per span and receives the span's `id`, `root_span_id`, `input`, `output`, `error`, `metadata`, and `span_attributes`. It must synchronously return a JSON-serializable value, or `null` to skip the span.

Published handlers run in QuickJS. `bt preprocessors push` bundles local imports into inline code. Node.js APIs, network access, and unbundled imports are unavailable.

## bt preprocessors push

Push one or more preprocessor definitions to Braintrust. `bt` scans the path for files matching `*.preprocessor.ts`, `*.preprocessor.js`, `*-preprocessor.ts`, or `*-preprocessor.js`, and pushes every definition each file exports.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt preprocessors push ./braintrust-preprocessors --project my-project
bt preprocessors push ./braintrust-preprocessors/conversation.preprocessor.ts --if-exists replace
```

If a preprocessor with the same slug already exists, the command fails by default. Add `--if-exists replace` to update it.

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<PATH>` | — | `.` | File or directory path(s) to scan for preprocessor definitions |
| `--file <PATH>` | `BRAINTRUST_PREPROCESSORS_PUSH_FILES` | — | Comma-separated file or directory paths (alternative to the positional argument) |
| `--if-exists <MODE>` | `BRAINTRUST_PREPROCESSORS_PUSH_IF_EXISTS` | `error` | Conflict behavior when a preprocessor with the same slug already exists: `error`, `replace`, or `ignore` |
| `--yes`, `-y` | `BRAINTRUST_PREPROCESSORS_PUSH_YES` | `false` | Skip the confirmation prompt |

Each definition can set `project` to a project name, or to an object with the project's `id` or `name`. Definitions without one use `--project` or your configured project.

## bt preprocessors bootstrap

Create a starter preprocessor file in the `braintrust-preprocessors/` directory (created if it does not exist). The starter returns each LLM span's output as an assistant message.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt preprocessors bootstrap 'Conversation'
bt preprocessors bootstrap 'Conversation' --file ./my-preprocessors/conversation.preprocessor.ts
```

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<NAME>` | — | — | Preprocessor name (required unless `--name` is used) |
| `--name <NAME>` | `BRAINTRUST_PREPROCESSORS_BOOTSTRAP_NAME` | — | Preprocessor name (alternative to the positional argument) |
| `--file <PATH>` | `BRAINTRUST_PREPROCESSORS_BOOTSTRAP_FILE` | `braintrust-preprocessors/<slug>.preprocessor.ts` | Output file or directory path. A file path must match the push file pattern |
| `--force`, `-f` | `BRAINTRUST_PREPROCESSORS_BOOTSTRAP_FORCE` | `false` | Overwrite an existing file |

## bt preprocessors preview

Run a local preprocessor on a trace in Braintrust's QuickJS runtime and print the output. Preview doesn't publish the preprocessor.

Open a trace in Braintrust's logs or an experiment and copy the URL from your browser's address bar. Pass it to `--url` in quotes to preserve its query parameters:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt preprocessors preview ./braintrust-preprocessors/conversation.preprocessor.ts --url "<BRAINTRUST_TRACE_URL>"
```

You can also select a project logs trace by root span ID. If the URL doesn't include a project, or you use `--trace-id`, also pass `--project` or `--project-id`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt preprocessors preview ./conversation.preprocessor.ts --trace-id <ROOT_SPAN_ID> --project my-project
```

If the file exports more than one definition, select one with `--export <NAME>`, or `--export default` for the default export.

**Flags**

| Flag | Env var | Default | Description |
| - | - | - | - |
| `<PATH>` | — | — | Preprocessor file to preview (required unless `--file` is used) |
| `--file <PATH>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_FILE` | — | Preprocessor file (alternative to the positional argument) |
| `--export <NAME>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_EXPORT` | — | Export to preview when the file contains multiple preprocessors |
| `--url <URL>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_URL` | — | Braintrust app URL of the trace to preprocess |
| `--project-id <ID>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_PROJECT_ID` | — | Project ID of the trace to preprocess |
| `--trace-id <ID>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_TRACE_ID` | — | Root span ID of the trace (alias: `--root-span-id`) |
| `--lookup-window <DURATION>` | `BRAINTRUST_PREPROCESSORS_PREVIEW_LOOKUP_WINDOW` | `30d` | Lookback window when resolving a URL's span ID (for example, `7d`, `90d`) |

## Use a preprocessor in a scorer

Pass `--preprocessor` to [`bt scorers create`](/docs/reference/cli/scorers#preprocessors) to build a prompt-based scorer's trace template variables with a pushed preprocessor:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt scorers create "Helpfulness" --model gpt-5.4-nano --messages @messages.json \
  --choice-scores '{"A":1,"B":0}' --preprocessor conversation
```

## Example workflow

With `bt` v0.26.0 or later and Node.js installed, bootstrap, preview, and push a preprocessor. Copy a trace URL from your browser's address bar for the preview step:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
# 1. Create a starter file in braintrust-preprocessors/
bt preprocessors bootstrap 'Conversation'

# 2. Run it against a real trace
bt preprocessors preview ./braintrust-preprocessors/conversation.preprocessor.ts \
  --url "<BRAINTRUST_TRACE_URL>"

# 3. Push to Braintrust when you're satisfied
bt preprocessors push ./braintrust-preprocessors --project my-project
```


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