bt functions - Braintrust

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 view

Inspect a function’s definition. The details shown depend on the function type: LLM functions show their prompt and model, code functions show their source (or a preview for bundled code), scorers show their parameters, and classifiers show their source facet, embedding model, and topics. Target a function by slug or ID, and optionally pin to a specific version. Without a slug, bt functions view prompts you to select a function interactively.

bt functions view my-function                          # View the latest version
bt functions view my-function --version <version>      # View a specific historical version
bt functions view --id <function-id>                   # Select by function ID
bt functions view my-function --web                    # Open the function in your browser

By default, bt functions view shows the latest version of a function. Pass --version to inspect an earlier version.

Flags

Flag	Env var	Default	Description
`--slug <SLUG>` / `-s`	—	—	Function slug to view (also accepted as a positional argument)
`--id <ID>`	`BT_FUNCTIONS_VIEW_ID`	—	Function ID selector (mutually exclusive with a slug)
`--version <VERSION>`	`BT_FUNCTIONS_VIEW_VERSION`	—	Version selector. Omit to view the latest version
`--web`	—	`false`	Open the function in your browser instead of printing to the terminal

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

​bt functions view

​Flags

​bt functions push

​Flags

​bt functions pull

​Flags

bt functions view

Flags

bt functions push

Flags

bt functions pull

Flags