BoundaryML/baml · error

usage: baml toolchain install <canary|nightly|version>

Error message

usage: baml toolchain install <canary|nightly|version>

What it means

`baml toolchain install` requires exactly one selector argument naming which toolchain to install: `canary`, `nightly`, or a specific version. When the selector argument is missing entirely, the `toolchain` function throws this usage error via `args.get(1).ok_or_else(...)`.

Source

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

        fs::create_dir_all(parent)?;
    }
    let tmp = path.with_extension("tmp");
    fs::write(&tmp, toml::to_string_pretty(value)?)?;
    fs::rename(tmp, path)?;
    Ok(())
}

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(" ")
                ));

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Provide a selector: `baml toolchain install canary`, `baml toolchain install nightly`, or `baml toolchain install <version>` (e.g. `0.210.0`).
  2. Run `baml toolchain install --help` or `baml toolchain --help` for usage.
  3. If the selector comes from a shell variable, verify it is non-empty before invoking.

Example fix

# before
baml toolchain install --force

# after
baml toolchain install canary --force
Defensive patterns

Strategy: validation

Validate before calling

selector="${SELECTOR:?SELECTOR must be set (canary|nightly|version)}"
case "$selector" in canary|nightly|[0-9]*.[0-9]*.[0-9]*) ;; *) echo "invalid selector: $selector" >&2; exit 1;; esac
baml toolchain install "$selector"

Type guard

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

Try / catch

try:
    subprocess.run(["baml", "toolchain", "install", selector], check=True)
except subprocess.CalledProcessError as e:
    if "usage: baml toolchain install" in e.stderr.decode():
        raise SystemExit("Selector missing — pass canary, nightly, or a version")

Prevention

When it happens

Trigger: Running `baml toolchain install` with no further arguments, or with only flags like `baml toolchain install --force` (the flag is scanned later but the selector slot is empty).

Common situations: Users forgetting the version selector, scripts calling `baml toolchain install` with an unset variable, or mistyping the subcommand so the selector lands in the wrong position.

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/acb7c0b22661bd4c. Report an issue: GitHub.