baml dev

The baml dev command starts a development server that watches your BAML source files for changes, automatically reloads the runtime, regenerates client code, and exposes your BAML functions via HTTP endpoints.

Usage

baml dev [OPTIONS]

Options

--from

string

default:"./baml_src"

Path to the directory containing your BAML source files.

--port

number

default:"2024"

Port number for the HTTP server.

--dotenv

boolean

default:"true"

Load environment variables from a .env file. Disable with --no-dotenv.

--dotenv-path

string

Path to a custom environment file. If not specified, looks for .env in the current directory.

--features

string[]

Enable specific features (can be specified multiple times).Available features:

beta - Enable beta features and suppress experimental warnings
display_all_warnings - Show all warnings in CLI output

What It Does

The baml dev command combines the functionality of baml serve with automatic reloading:

Starts HTTP server - Exposes BAML functions as REST endpoints on the specified port
Watches for changes - Monitors all files in baml_src/ for modifications
Auto-regenerates code - Runs baml generate whenever BAML files change
Hot reloads runtime - Updates the running server with new function definitions without restart
Provides debugging endpoints - Swagger UI, OpenAPI spec, and health checks

File Watching

The dev server uses efficient file watching with:

200ms debounce - Groups rapid file changes to avoid excessive reloads
Recursive watching - Monitors all subdirectories in baml_src/
Automatic detection - Picks up new files, deletions, and modifications

Examples

Start with default settings

Start the dev server on port 2024:

baml dev

Output:

Starting BAML development server on port 2024
Generated 1 baml_client: ../baml_client
BAML server listening on http://0.0.0.0:2024

Use a custom port

baml dev --port 3000

Specify BAML source directory

baml dev --from ./my-baml-project/baml_src

Use custom environment file

baml dev --dotenv-path .env.development

Enable beta features

baml dev --features beta

HTTP Endpoints

Once running, the dev server exposes:

Function Endpoints

POST /call/:function_name - Call a BAML function

curl -X POST http://localhost:2024/call/ExtractResume \
  -H "Content-Type: application/json" \
  -d '{"resume": "John Doe\nSoftware Engineer"}'

Response:

{
  "name": "John Doe",
  "title": "Software Engineer",
  "email": null
}

POST /stream/:function_name - Stream results from a BAML function

curl -X POST http://localhost:2024/stream/GenerateStory \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A story about a robot"}'

Returns server-sent events (SSE) with incremental results.

Debugging Endpoints

GET /docs - Interactive Swagger UI documentation Open http://localhost:2024/docs in your browser to:

Browse all available functions
Test function calls interactively
View request/response schemas

GET /openapi.json - OpenAPI specification

curl http://localhost:2024/openapi.json

Download the full API specification for use with other tools. GET /_debug/ping - Health check endpoint

curl http://localhost:2024/_debug/ping

Response:

{"status": "ok"}

GET /_debug/status - Server status and authentication check

curl http://localhost:2024/_debug/status

Response:

{
  "authz": {
    "enforcement": "none"
  }
}

Hot Reload Behavior

When you save a BAML file:

Change detected (200ms debounce window)

Runtime reloads

Reloading - 1 file changed
Generated 1 baml_client: ../baml_client
Reloaded runtime in 45ms (1 file changed)

Server continues running with updated function definitions

If reload fails:

Failed to reload runtime: Parser error at line 42: unexpected token

The server continues running with the last valid configuration.

Development Workflow

Typical development workflow with baml dev:

1. Start the server

baml dev

2. Open Swagger UI

Navigate to http://localhost:2024/docs in your browser.

3. Edit BAML files

Modify baml_src/functions.baml:

function AnalyzeSentiment(text: string) -> Sentiment {
  client GPT4
  prompt #"
    Analyze the sentiment of this text: {{ text }}
    
    Return the result as: {{ ctx.output_format }}
  "#
}

class Sentiment {
  sentiment "positive" | "negative" | "neutral"
  confidence float
}

4. See automatic reload

Reloading - 1 file changed
Generated 1 baml_client: ../baml_client  
Reloaded runtime in 52ms (1 file changed)

5. Test immediately

In Swagger UI or via curl:

curl -X POST http://localhost:2024/call/AnalyzeSentiment \
  -H "Content-Type: application/json" \
  -d '{"text": "This is amazing!"}'

6. Iterate quickly

Modify prompt, add fields, change logic - changes are reflected immediately without manual restart.

Authentication

The dev server supports optional authentication via the x-baml-api-key header.

Enable authentication

Set the BAML_PASSWORD environment variable:

export BAML_PASSWORD=my-secret-key
baml dev

Or in .env:

BAML_PASSWORD=my-secret-key

Make authenticated requests

curl -X POST http://localhost:2024/call/MyFunction \
  -H "Content-Type: application/json" \
  -H "x-baml-api-key: my-secret-key" \
  -d '{"arg": "value"}'

Without the header:

{
  "error": "Unauthorized"
}

Troubleshooting

Port already in use

Error: “Failed to bind to port 2024” Solution: Use a different port:

baml dev --port 3000

Or kill the process using the port:

# Find process
lsof -i :2024

# Kill it
kill -9 <PID>

Changes not detected

Issue: File changes don’t trigger reload Solution:

Ensure you’re editing files inside baml_src/
Check file permissions allow reading
Save the file (some editors use atomic writes that may cause issues)
Try restarting the dev server

Reload failures

Error: “Failed to reload runtime: Parser error” Solution: Fix the syntax error in your BAML file. The server continues running with the last valid configuration. Check the error message for:

Line number of the error
Specific syntax issue
File containing the problem

API key errors when testing

Error: 401 Unauthorized or “Missing API key” Solution: Ensure LLM provider API keys are set:

# In .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-...

# Or export directly
export OPENAI_API_KEY=sk-...
baml dev

Memory issues with many changes

Issue: Server slows down or crashes after many reloads Solution: Restart the dev server periodically:

# Stop with Ctrl+C
# Restart
baml dev

Comparison with baml serve

Feature	`baml dev`	`baml serve`
HTTP endpoints	✓	✓
File watching	✓	✗
Auto reload	✓	✗
Auto regenerate	✓	✗
Production use	✗	✓
Stability	Development	Production

Use baml dev for:

Local development
Rapid iteration
Testing changes immediately

Use baml serve for:

Production deployments
Stable API endpoints
When you don’t need hot reload

baml serve - Production HTTP server without hot reload
baml generate - Manually generate client code
baml test - Run automated tests
baml init - Initialize a new BAML project

BAML Language

Type System

CLI

Client API

LLM Providers

Usage

Options

What It Does

File Watching

Examples

Start with default settings

Use a custom port

Specify BAML source directory

Use custom environment file

Enable beta features

HTTP Endpoints

Function Endpoints

Debugging Endpoints

Hot Reload Behavior

Development Workflow

1. Start the server

2. Open Swagger UI

3. Edit BAML files

4. See automatic reload

5. Test immediately

6. Iterate quickly

Authentication

Enable authentication

Make authenticated requests

Troubleshooting

Port already in use

Changes not detected

Reload failures

API key errors when testing

Memory issues with many changes

Comparison with baml serve

Build docs developers (and LLMs) love

BAML Language

Type System

CLI

Client API

LLM Providers

​Usage

​Options

​What It Does

​File Watching

​Examples

​Start with default settings

​Use a custom port

​Specify BAML source directory

​Use custom environment file

​Enable beta features

​HTTP Endpoints

​Function Endpoints

​Debugging Endpoints

​Hot Reload Behavior

​Development Workflow

​1. Start the server

​2. Open Swagger UI

​3. Edit BAML files

​4. See automatic reload

​5. Test immediately

​6. Iterate quickly

​Authentication

​Enable authentication

​Make authenticated requests

​Troubleshooting

​Port already in use

​Changes not detected

​Reload failures

​API key errors when testing

​Memory issues with many changes

​Comparison with baml serve

​Related Commands

Build docs developers (and LLMs) love

Usage

Options

What It Does

File Watching

Examples

Start with default settings

Use a custom port

Specify BAML source directory

Use custom environment file

Enable beta features

HTTP Endpoints

Function Endpoints

Debugging Endpoints

Hot Reload Behavior

Development Workflow

1. Start the server

2. Open Swagger UI

3. Edit BAML files

4. See automatic reload

5. Test immediately

6. Iterate quickly

Authentication

Enable authentication

Make authenticated requests

Troubleshooting

Port already in use

Changes not detected

Reload failures

API key errors when testing

Memory issues with many changes

Comparison with baml serve

Related Commands