bt functions - Braintrust

bt functions manages function definitions stored in Braintrust, including tools, scorers, and LLM functions. Running bt functions without a subcommand is equivalent to running bt functions list.

bt functions list
bt functions view my-function
bt functions view fn_123
bt functions view --id fn_123
bt functions invoke my-function --input '{"key":"value"}'
bt functions push --file ./functions
bt functions pull --output-dir ./braintrust

bt functions list

List functions in the current project.

bt functions list
bt functions list --type scorer

Flags

Flag	Description
`--type`, `-t <FUNCTION_TYPE>`	Filter by function type: `llm`, `scorer`, `task`, `tool`, `custom-view`, `preprocessor`, `facet`, `classifier`, `tag`, or `parameters`

bt functions view

Inspect a function’s definition. Depending on how the function is configured, the output can include:

Prompt and model settings
Inline code or a preview of an uploaded code bundle
Scorer parameters
Classifier details, including its source facet, embedding model, and topics

Target a function by slug or ID. A positional value beginning with fn_ or func_ is treated as a function ID. Without a selector, bt functions view prompts you to select a function in an interactive terminal.

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
`--type <FUNCTION_TYPE>` / `-t`	—	—	Filter by function type for interactive selection

bt functions invoke

Invoke a function by slug. Without a slug, bt functions invoke prompts you to select a function in an interactive terminal. Use --input to pass JSON input, --message to pass one or more user messages to an LLM function, and --mode to choose the response format. In a non-interactive environment, you can also pipe JSON input to stdin.

bt functions invoke my-fn --input '{"key": "value"}'
bt functions invoke my-fn --message "What is 2+2?"
bt functions invoke my-fn -i '{"my-var": "A very long text..."}' -m "Summarize this"
bt functions invoke my-fn --mode json --version abc123

Flags

Flag	Description
`--slug <SLUG>` / `-s`	Function slug to invoke (also accepted as a positional argument)
`--input <INPUT>` / `-i`	JSON input to the function
`--message <MESSAGE>` / `-m`	User message for an LLM function. Pass multiple times to provide multiple messages
`--mode <MODE>`	Response format: `auto`, `json`, `text`, or `parallel`
`--version <VERSION>`	Pin to a specific function version
`--type <FUNCTION_TYPE>` / `-t`	Filter by function type for interactive selection

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. Pass files or directories as positional arguments or with --file. If you omit them, bt functions push scans the current directory. Supported source extensions are .ts, .tsx, .js, .jsx, and .py. 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
bt functions push --file ./functions

Python bundle paths must not contain spaces or other whitespace characters. Rename the file or directory if its path contains whitespace.

Flags

Flag	Env var	Default	Description
`--file <PATH>`	`BT_FUNCTIONS_PUSH_FILES`	—	File or directory path(s) to scan. Repeatable and 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. Accepts space- or comma-delimited values. The Braintrust SDK is bundled by default and does not need to be listed
`--runner <RUNNER>`	`BT_FUNCTIONS_PUSH_RUNNER`	—	Override runner binary, such as `tsx`, `vite-node`, `deno`, or `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 my-scorer                           # Pull a specific function by slug
bt functions pull scorer-a scorer-b                   # Pull multiple functions
bt functions pull --slug scorer-a --slug scorer-b     # Pull multiple functions with flags
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 and comma-delimited
`--id <ID>`	`BT_FUNCTIONS_PULL_ID`	—	Function ID selector
`--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 existing output files, including dirty or untracked files

bt functions delete

Delete a function by slug. Without a slug, bt functions delete prompts you to select a function interactively.

bt functions delete my-function
bt functions delete my-function --force

Flags

Flag	Description
`--slug <SLUG>` / `-s`	Function slug to delete (also accepted as a positional argument)
`--force` / `-f`	Skip the confirmation prompt. Requires a function slug
`--type <FUNCTION_TYPE>` / `-t`	Filter by function type for interactive selection

Use the shared --org, --project, and --profile global flags to select the Braintrust context. The list, view, invoke, push, and pull subcommands also support --json output.

​bt functions list

​bt functions view

​bt functions invoke

​bt functions push

​bt functions pull

​bt functions delete

bt functions list

bt functions view

bt functions invoke

bt functions push

bt functions pull

bt functions delete