> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.boundaryml.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.boundaryml.com/_mcp/server.

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](./dev)

## Options

| Option               | Description                                                  | Default      |
| -------------------- | ------------------------------------------------------------ | ------------ |
| `--from <PATH>`      | Path to the `baml_src` directory                             | `./baml_src` |
| `--port <PORT>`      | Port to expose BAML on                                       | `2024`       |
| `--no-version-check` | Generate `baml_client` without checking for version mismatch | `false`      |

## 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

```bash 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

```bash 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](/ref/baml_client/type-builder)
* the [Collector API](/guide/baml-advanced/collector-track-tokens)
* the [Modular API](/guide/baml-advanced/modular-api)
* custom trace annotations for [Boundary Studio](/guide/boundary-cloud/observability/tracking-usage)

## 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:
   ```bash
   curl http://localhost:2024/_debug/ping
   ```

2. Call a function:

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

   ```bash 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.