bt functions manages function definitions stored in Braintrust — tools, scorers, LLM functions, and more.
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.
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
Python bundle paths must not contain spaces or other whitespace characters. Rename your directory or use a symlink if your path contains spaces.
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.
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 |
