Generate the BAML Client
Once you’ve defined a function in BAML, you need to generate code in your language of choice to call that function: we call this generating the BAML client.
If you use VSCode, the BAML extension will re-generate the client every time you save a BAML file. Otherwise, you can generate the client manually:
Best Practices
Define a generator
clause
baml-cli init
, then one has already been generated for you!Each generator
that you define in your BAML project will tell baml-cli generate
to generate code for a specific target language. You can define
multiple generator
clauses in your BAML project, and baml-cli generate
will
generate code for each of them.
Generate the BAML client on-demand
Although you can check in the generated BAML client, we recommend that you
instead add it to your .gitignore
and generate it on-demand when you
build/release your code:
- this will make your PRs more readable;
- this will save you from handling merge conflicts in generated code; and
- this will ensure a single source-of-truth for your BAML code (and prevent your client from falling out of sync with your BAML code).
To add the generated client to your .gitignore
, you can run:
and then you just need to run baml-cli generate
in your CI/CD build/release
workflows. Here’s what that might look like in a GitHub Actions workflow file:
Troubleshooting version conflicts
baml_client
can be generated in 2 ways:
- VSCode extension
- the installed baml dependency (e.g.,
baml-py
)
Since the extension auto-updates, it’s possible that it stops generating the client due to a version mismatch with the generator
version. You might see an error like:
To fix any version mismatch issues, update all these things to the same version:
- VSCode extension
- the installed baml dependency (e.g.,
baml-py
)
- python:
pip install --upgrade baml-py
- typescript:
npm install @boundaryml/baml@latest
- the
version
in yourgenerator
clause
Only the minor and major versions are checked for compatibility (0.0.x).
You can also tweak the generator settings below for a better experience.
VSCode generator settings
If set, will make the extension use the baml-cli you have installed on your system to generate the client. This prevents mismatches between the generated code and the installed BAML package.
If you use unix, you can run where baml-cli
in your project to figure out what the path is.
If you have multiple BAML projects, ensure that this path is set to baml package installed for that project.
If you’re using it via npx
, you can set it as npx @boundaryml/baml@VERSION
where VERSION
is the version you want to pin your version to.
Possible options: always
, never
.
If you choose never
, you will have to run the baml-cli generate
command manually.
Restarts the TypeScript Server in VSCode when the BAML extension generates the TypeScript baml_client files. VSCode has some issues picking up newly added directories and files, so this is a workaround for that.
If it’s not enabled, you may have to reload the TS server yourself to get it to recognize the new types.
baml-cli generate
arguments
Path to the BAML source directory. This is where the BAML files are located.
If set, it will disable checking the BAML source version with the installed BAML package version before generating code.