docs: add reference docs about env vars (#945)

Also:
- speed up test_node_generator in CI
- surface more context when generation fails

.github/workflows/primary.yml

@@ -64,7 +64,7 @@ jobs:
         run: pnpm install --frozen-lockfile
         working-directory: engine/language_client_typescript
       - name: Build Node
-        run: pnpm build
+        run: pnpm build:debug
         working-directory: engine/language_client_typescript
       - name: Install Node
         run: pnpm install --frozen-lockfile

docs/docs.yml

@@ -182,12 +182,14 @@ navigation:
         path: docs/comparisons/pydantic.mdx
   - section: Reference
     contents:
+      - page: Contact Us
+        path: docs/contact.mdx
+      - page: Environment Variables
+        path: docs/reference/env-vars.mdx
       - section: Incidents
         contents:
           - page: SSRF Issue in fiddle-proxy (July 2024)
             path: docs/incidents/2024-07-10-ssrf-issue-in-fiddle-proxy.mdx
-      - page: Contact Us
-        path: docs/contact.mdx
 
 navbar-links:
   - type: github

docs/docs/reference/env-vars.mdx

@@ -0,0 +1,50 @@
+---
+slug: docs/reference/env-vars
+---
+
+This is a full list of all environment variables that the BAML runtime respects.
+
+`BAML_LOG`
+
+- defaults to `warn` when used as a library, defaults to `info` in `baml-cli`
+- sets the log level for BAML
+- can be one of `error`, `warn`, `info`, `debug`, or `trace` (note that `debug` and `trace` are reserved for internal use and are not stable)
+
+`BAML_LOG_STYLE`
+
+- `auto` (default) will attempt to print style characters, but don’t force the issue. If the console isn’t available on Windows, or if TERM=dumb, for example, then don’t print colors.
+- `always` will always print style characters even if they aren’t supported by the terminal. This includes emitting ANSI colors on Windows if the console API is unavailable.
+- `never` will never print style characters.
+
+`BAML_PASSWORD`
+
+Sets the password for `baml-cli serve`. See [Deploying BAML Projects / Docker (OpenAPI)](/docs/get-started/deploying/openapi) for more details.
+
+- if unset, all incoming HTTP requests to `baml-cli serve` are authorized
+- if set, all incoming HTTP requests must attach the password using either HTTP basic auth or the `X-BAML-API-KEY` header
+
+`DANGER_ACCEPT_INVALID_CERTS`
+
+- when `DANGER_ACCEPT_INVALID_CERTS=1`, turns off HTTPS cert validation
+- only set this in development or testing environments
+
+## Clients
+
+<Note>
+  You may also have your own environment variable references in clients, e.g. using
+  `api_key env.MY_API_KEY` in a client definition.
+</Note>
+
+`ANTHROPIC_API_KEY`
+
+Attached as `Authorization: Bearer $ANTHROPIC_API_KEY` to all `anthropic/<model>` clients and the
+default `Haiku` and `Sonnet` clients created by `baml-cli init`.
+
+See the [`anthropic` provider docs](/docs/snippets/clients/providers/anthropic) for more details.
+
+`OPENAI_API_KEY`
+
+Attached as `Authorization: Bearer $OPENAI_API_KEY` to all `openai/<model>` clients and the
+default `GPT4o` and `GPT4oMini` clients created by `baml-cli init`.
+
+See the [`openai` provider docs](/docs/snippets/clients/providers/openai) for more details.

engine/baml-runtime/src/cli/generate.rs

@@ -28,12 +28,15 @@ impl GenerateArgs {
     }
 
     fn generate_clients(&self, defaults: super::RuntimeCliDefaults) -> Result<()> {
-        let runtime = BamlRuntime::from_directory(&self.from, std::env::vars().collect())?;
-        let src_files = baml_src_files(&self.from)?;
+        let runtime = BamlRuntime::from_directory(&self.from, std::env::vars().collect())
+            .context("Failed to build BAML runtime")?;
+        let src_files = baml_src_files(&self.from)
+            .context("Failed while searching for .baml files in baml_src/")?;
         let all_files = src_files
             .iter()
             .map(|k| Ok((k.clone(), std::fs::read_to_string(&k)?)))
-            .collect::<Result<_>>()?;
+            .collect::<Result<_>>()
+            .context("Failed while reading .baml files in baml_src/")?;
         let generated = runtime
             .run_generators(&all_files, self.no_version_check)
             .context("Client generation failed")?;
@@ -62,19 +65,25 @@ impl GenerateArgs {
             // Normally `baml_client` is added via the generator, but since we're not running the generator, we need to add it manually.
             let output_dir_relative_to_baml_src = PathBuf::from("..");
             let version = env!("CARGO_PKG_VERSION");
-            let generate_output = runtime.generate_client(
-                &client_type,
-                &internal_baml_codegen::GeneratorArgs::new(
-                    &output_dir_relative_to_baml_src.join("baml_client"),
-                    &self.from,
-                    all_files.iter(),
-                    version.to_string(),
-                    false,
-                    default_client_mode,
-                    // TODO: this should be set if user is asking for openapi
-                    vec![],
-                )?,
-            )?;
+            let generate_output = runtime
+                .generate_client(
+                    &client_type,
+                    &internal_baml_codegen::GeneratorArgs::new(
+                        &output_dir_relative_to_baml_src.join("baml_client"),
+                        &self.from,
+                        all_files.iter(),
+                        version.to_string(),
+                        false,
+                        default_client_mode,
+                        // TODO: this should be set if user is asking for openapi
+                        vec![],
+                    )
+                    .context("Failed while resolving .baml paths in baml_src/")?,
+                )
+                .context(format!(
+                    "Failed to run generator for {client_type} in {}",
+                    output_dir_relative_to_baml_src.display()
+                ))?;
 
             log::info!(
                 "Generated 1 baml_client: {}",