For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help on Discord
HomeGuideExamplesBAML ReferencePlaygroundAgents.mdChangelog
HomeGuideExamplesBAML ReferencePlaygroundAgents.mdChangelog
    • Overview
  • baml-cli
    • init
    • generate
    • test
    • serve
    • dev
    • fmt
  • Language Reference
    • Types
    • function
    • test
    • template_string
    • client<llm>
    • class
    • enum
    • generator
  • Generated baml_client
    • with_options(..)
    • AbortSignal / Cancellation
    • Collector
    • logging / env vars
    • AsyncClient / SyncClient
    • TypeBuilder
    • ClientRegistry
    • client Option
    • OnTick
    • Multimodal
    • Image
    • Audio
    • Pdf
    • Video
  • Attributes
    • What are attributes?
    • @alias / @@alias
    • @description / @@description
    • @skip
    • @assert
    • @check
    • Jinja in Attributes
    • @@dynamic
  • LLM Client Providers
    • Overview
    • AWS Bedrock
    • Anthropic
    • Google AI: Gemini
    • Google: Vertex
    • OpenAI
    • OpenAI Responses API
    • OpenAI from Azure
    • OpenRouter
    • openai-generic
    • Microsoft Foundry (openai-generic)
    • Cerebras (openai-generic)
    • Groq (openai-generic)
    • Hugging Face (openai-generic)
    • Keywords AI (openai-generic)
    • Llama API (openai-generic)
    • Litellm (openai-generic)
    • LM Studio (openai-generic)
    • Ollama (openai-generic)
    • Vercel AI Gateway (openai-generic)
    • Tinfoil (openai-generic)
    • TogetherAI (openai-generic)
    • Unify AI (openai-generic)
    • vLLM (openai-generic)
  • LLM Client Strategies
    • Timeout Configuration
    • Retry Policy
    • Fallback
    • Round Robin
  • Prompt Syntax
    • What is jinja?
    • Jinja Filters
    • ctx.output_format
    • ctx.client
    • _.role
    • Variables
    • Conditionals
    • Loops
  • Editor Extension Settings
    • baml.cliPath
    • baml.generateCodeOnSave
    • baml.enablePlaygroundProxy
    • baml.syncExtensionToGeneratorVersion
Help on Discord
LogoLogo
On this page
  • Usage
  • Options
  • Description
  • Endpoints
  • Stability
  • Authentication
  • Examples
  • Testing
baml-cli

serve

Was this page helpful?
Edit this page
Previous

dev

Next
Built with

The serve command starts a BAML-over-HTTP API server that exposes your BAML functions via HTTP endpoints. This feature allows you to interact with your BAML functions through a RESTful API interface.

Usage

baml-cli serve [OPTIONS]

If you’re actively developing, you can use the dev command to include hot-reload functionality:

baml-cli dev [OPTIONS]

See more

Options

OptionDescriptionDefault
--from <PATH>Path to the baml_src directory./baml_src
--port <PORT>Port to expose BAML on2024
--no-version-checkGenerate baml_client without checking for version mismatchfalse

Description

The serve command performs the following actions:

  1. Exposes BAML functions as HTTP endpoints on the specified port.
  2. Provides authentication middleware for secure access.

Endpoints

POST /call/:function_name: Call a BAML function

curl
$curl \
>  -X POST \
>  "http://localhost:2024/call/MyFunctionName" \
>  -H "Content-Type: application/json" \
>  -d '{"arg1": "value1", "arg2": "value2"}'

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

curl
$curl \
>  -X POST \
>  "http://localhost:2024/stream/MyFunctionName" \
>  -H "Content-Type: application/json" \
>  -d '{"arg1": "value1", "arg2": "value2"}'

Debugging

  • GET /docs: Interactive API documentation (Swagger UI)
  • GET /openapi.json: OpenAPI specification for the BAML functions
  • GET /_debug/ping: Health check endpoint
  • GET /_debug/status: Server status and authentication check

Stability

baml-cli serve is currently in Tier 2 stability. This means that the CLI and the HTTP APIs are stable, but there are a number of features which are not yet available:

  • the TypeBuilder API
  • the Collector API
  • the Modular API
  • custom trace annotations for Boundary Studio

Authentication

We support the header: x-baml-api-key

Set the BAML_PASSWORD environment variable to enable authentication.

Examples

  1. Start the server with default settings:

    baml-cli serve --preview

  2. Start the server with a custom source directory and port:

    baml-cli serve --from /path/to/my/baml_src --port 3000 --preview

Testing

To test the server, you can use the following curl commands:

  1. Check if the server is running:

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

  2. Call a function:

    $curl -X POST \
    >   http://localhost:2024/call/MyFunctionName \
    >   -H "Content-Type: application/json" \
    >   -d '{"arg1": "value1", "arg2": "value2"}'
    API Key
    $curl -X POST \
    >   http://localhost:2024/call/MyFunctionName \
    >   -H "Content-Type: application/json" \
    >   -H "x-baml-api-key: ${BAML_PASSWORD}" \
    >   -d '{"arg1": "value1", "arg2": "value2"}'

  3. Access the API documentation: Open http://localhost:2024/docs in your web browser.