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

# bt functions

> Upload and download function definitions to and from Braintrust

`bt functions` manages function definitions stored in Braintrust — tools, scorers, LLM functions, and more.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt functions list                          # List all functions
bt functions view my-function              # View a function
bt functions invoke my-function            # Invoke a function
bt functions push my_tools.ts              # Upload a TypeScript function file
bt functions push src/tools.py             # Upload a Python function file
bt functions pull --slug my-scorer         # Download a function to a local file
```

## bt functions push

Upload local TypeScript or Python function definitions to Braintrust. The CLI discovers functions registered via the Braintrust SDK, bundles them, and uploads them to the API.

**TypeScript bundling:** `bt functions push` uses esbuild (resolved from your project's `node_modules`) to bundle TypeScript/JavaScript files. The Braintrust SDK (`braintrust`, `autoevals`, `@braintrust/*`) is bundled into the archive by default so functions are self-contained. Use `--external-packages` to mark additional packages as external if needed.

**Python bundling:** For Python files, the CLI collects `.py` source files and vendors the `braintrust` SDK package into the archive so it is available at runtime.

**Function discovery:** The CLI runs your file through the Braintrust SDK to discover registered functions. Functions are registered using builder methods such as `project.tools.create()` and `project.scorers.create()`, which populate a global registry that `push` reads at upload time.

**Zod and Pydantic schemas:** Parameter schemas defined with Zod (TypeScript) or Pydantic (Python) are serialized and stored alongside the function definition in Braintrust.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt functions push my_tools.ts
bt functions push src/tools.py src/scorers.py
bt functions push --language javascript my_tools.ts
bt functions push --if-exists replace my_tools.ts
bt functions push --external-packages lodash,axios my_tools.ts
```

<Warning>
  Python bundle paths must not contain spaces or other whitespace characters. Rename your directory or use a symlink if your path contains spaces.
</Warning>

### Flags

| Flag                         | Env var                                     | Default | Description                                                                                                                                                      |
| ---------------------------- | ------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--file <PATH>`              | `BT_FUNCTIONS_PUSH_FILES`                   | —       | File or directory path(s) to scan (repeatable; comma-delimited)                                                                                                  |
| `--if-exists <MODE>`         | `BT_FUNCTIONS_PUSH_IF_EXISTS`               | `error` | Behavior when slug already exists: `error`, `replace`, or `ignore`                                                                                               |
| `--language <LANG>`          | `BT_FUNCTIONS_PUSH_LANGUAGE`                | `auto`  | Force language: `auto`, `javascript`, or `python`                                                                                                                |
| `--external-packages <PKGS>` | `BT_FUNCTIONS_PUSH_EXTERNAL_PACKAGES`       | —       | Additional packages to exclude from JS bundling (repeatable; space or comma-delimited). The Braintrust SDK is bundled by default and does not need to be listed. |
| `--runner <RUNNER>`          | `BT_FUNCTIONS_PUSH_RUNNER`                  | —       | Override runner binary (e.g. `tsx`, `vite-node`, `python`)                                                                                                       |
| `--tsconfig <PATH>`          | `BT_FUNCTIONS_PUSH_TSCONFIG`                | —       | tsconfig path for the JS runner and bundler                                                                                                                      |
| `--requirements <PATH>`      | `BT_FUNCTIONS_PUSH_REQUIREMENTS`            | —       | Python requirements file                                                                                                                                         |
| `--create-missing-projects`  | `BT_FUNCTIONS_PUSH_CREATE_MISSING_PROJECTS` | `true`  | Create referenced projects when they do not exist                                                                                                                |
| `--terminate-on-failure`     | `BT_FUNCTIONS_PUSH_TERMINATE_ON_FAILURE`    | `false` | Stop after the first hard failure                                                                                                                                |
| `--yes` / `-y`               | —                                           | —       | Skip confirmation prompts                                                                                                                                        |

## bt functions pull

Download function definitions from Braintrust to local files. Target functions by slug or ID, choose the output language, and control what happens when local files already exist.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt functions pull --slug my-scorer                    # Pull a specific function by slug
bt functions pull --slug scorer-a --slug scorer-b     # Pull multiple functions
bt functions pull --language python                   # Output as Python
bt functions pull --output-dir ./functions            # Write to a custom directory
bt functions pull --force                             # Overwrite local files
```

### Flags

| Flag                   | Env var                        | Default        | Description                                             |
| ---------------------- | ------------------------------ | -------------- | ------------------------------------------------------- |
| `--slug <SLUG>` / `-s` | `BT_FUNCTIONS_PULL_SLUG`       | —              | Function slug(s) to pull (repeatable; comma-delimited)  |
| `--id <ID>`            | `BT_FUNCTIONS_PULL_ID`         | —              | Function ID selector (mutually exclusive with `--slug`) |
| `--language <LANG>`    | `BT_FUNCTIONS_PULL_LANGUAGE`   | `typescript`   | Output language: `typescript` or `python`               |
| `--output-dir <PATH>`  | `BT_FUNCTIONS_PULL_OUTPUT_DIR` | `./braintrust` | Destination directory for generated files               |
| `--project-id <ID>`    | `BT_FUNCTIONS_PULL_PROJECT_ID` | —              | Filter by project ID                                    |
| `--version <VERSION>`  | `BT_FUNCTIONS_PULL_VERSION`    | —              | Version selector                                        |
| `--force`              | `BT_FUNCTIONS_PULL_FORCE`      | `false`        | Overwrite local files even when dirty                   |
| `--verbose`            | —                              | `false`        | Show skipped files in output                            |