What causes "usage: baml toolchain use " in BoundaryML/baml?

Pass a selector: `baml toolchain use canary`, `nightly`, a version, or a path to a local toolchain.

usage: baml toolchain use <canary|nightly|version|path>

Error message

usage: baml toolchain use <canary|nightly|version|path>

What it means

`baml toolchain use` requires a selector argument (`canary`, `nightly`, a version, or a local path). The `toolchain` function throws this usage error when `args.get(1)` is None, because there is no toolchain to switch to.

Source

Thrown at baml_language/crates/baml/src/main.rs:364

}

fn toolchain(args: Vec<String>) -> Result<()> {
    let (args, manifest_base_url) = parse_manifest_base_url(args)?;
    match args.first().map(String::as_str) {
        Some("--help" | "-h" | "help") | None => {
            print!("{TOOLCHAIN_HELP}");
            Ok(())
        }
        Some("install") => {
            let selector = args
                .get(1)
                .ok_or_else(|| anyhow!("usage: baml toolchain install <canary|nightly|version>"))?;
            let force = args.iter().any(|arg| arg == "--force");
            install_toolchain(selector, false, manifest_base_url.as_deref(), force)
        }
        Some("use") => {
            let selector = args.get(1).ok_or_else(|| {
                anyhow!("usage: baml toolchain use <canary|nightly|version|path>")
            })?;
            use_toolchain(selector, manifest_base_url.as_deref())
        }
        Some("pin") => {
            let selector = args.get(1).ok_or_else(|| {
                anyhow!("usage: baml toolchain pin <canary|nightly|version|path>")
            })?;
            if args.len() > 2 {
                return Err(anyhow!(
                    "usage: baml toolchain pin <canary|nightly|version|path>\nunexpected arguments: {}",
                    args[2..].join(" ")
                ));
            }
            pin_toolchain(selector, manifest_base_url.as_deref())
        }
        Some("update") => update_toolchain(manifest_base_url.as_deref()),
        Some("status") => status_toolchain(manifest_base_url.as_deref()),
        Some("list") => {

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass a selector: `baml toolchain use canary`, `nightly`, a version, or a path to a local toolchain.
Run `baml toolchain list` to see installed toolchains you can select.
Quote shell variables to catch empty values early: `baml toolchain use "$VERSION"`.

Example fix

# before
VERSION=""
baml toolchain use $VERSION

# after
VERSION="nightly"
baml toolchain use "$VERSION"

Defensive patterns

Strategy: validation

Validate before calling

selector="${SELECTOR:?SELECTOR must be set}"
[ -n "$selector" ] || { echo "empty selector" >&2; exit 1; }
baml toolchain use "$selector"

Type guard

function isValidUseSelector(s: string): boolean {
  return s === "canary" || s === "nightly" || /^\d+\.\d+\.\d+$/.test(s) || s.startsWith("/");
}

Try / catch

try:
    subprocess.run(["baml", "toolchain", "use", selector], check=True)
except subprocess.CalledProcessError as e:
    if "usage: baml toolchain use" in e.stderr.decode():
        raise SystemExit("Provide canary|nightly|version|path to `toolchain use`")

Prevention

Quote interpolated variables so empty values fail fast and visibly.
Run `baml toolchain list` first to confirm a selectable target exists.
For paths, use absolute paths to avoid ambiguity.

When it happens

Trigger: Running `baml toolchain use` with no argument, or with only flags following the subcommand so the selector slot is empty.

Common situations: Scripts with an unset/empty version variable (`baml toolchain use $VERSION` with VERSION empty), or users forgetting that `use` accepts a path and passing the path in the wrong place.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/a6dbdb044832f53b. Report an issue: GitHub.