`baml update` is ambiguous. To use the latest version of…

Error message

`baml update` is ambiguous.
To use the latest version of BAML, run `baml toolchain update`.
To use the latest BAML toolchain selector, run `baml self-update`.

What it means

run_cli deliberately rejects the bare `baml update` invocation because it is ambiguous: it could mean updating the BAML version used by a project or updating the toolchain selector binary itself. The CLI exits with a message directing users to `baml toolchain update` (latest BAML version) or `baml self-update` (latest toolchain selector).

Solutions

Run `baml toolchain update` to get the latest BAML version for your project.
Run `baml self-update` to update the BAML toolchain selector binary itself.
Update scripts/docs to use the explicit subcommands instead of `baml update`.

Example fix

// before
baml update
// after
baml toolchain update   # or: baml self-update

Defensive patterns

Strategy: validation

Validate before calling

# replace ambiguous update in scripts
case "$cmd" in update) echo "use 'baml toolchain update' or 'baml self-update'"; exit 1;; esac

Prevention

Never script bare `baml update`
Use explicit subcommands: baml toolchain update / baml self-update
Update internal docs/aliases that reference the old command

When it happens

Trigger: Invoke the CLI with `update` as the first argument (argv[1] == "update"), e.g. `baml update`.

Common situations: Habit from other CLIs (npm update, rustup update) where `update` is a generic subcommand; outdated docs or tutorials referencing a former `baml update` command.

Related errors

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

Appendix: source

Thrown at baml_language/crates/baml_cli/src/lib.rs:152

            // No tests were found
            ExitCode::NoTestsRun => 5,
            // `baml query` contract (documented per-command)
            ExitCode::QueryIncomplete => 1,
            ExitCode::QueryInvalid => 2,
            ExitCode::QueryBudgetExhausted => 3,
            ExitCode::QueryCancelled => 4,
            ExitCode::QueryFailed => 5,
        }
    }
}

/// Run the CLI with the given arguments.
///
/// Dispatches to one of: `run`, `check`, `generate`, `test`, `pack`,
/// `fmt`, ... `baml run` is the top-level entry for standalone execution.
pub fn run_cli(argv: Vec<String>) -> Result<ExitCode> {
    if argv.get(1).map(String::as_str) == Some("update") {
        return Err(anyhow!(
            "`baml update` is ambiguous.\n\
             To use the latest version of BAML, run `baml toolchain update`.\n\
             To use the latest BAML toolchain selector, run `baml self-update`."
        ));
    }
    let cli = commands::RuntimeCli::parse_from_smart(argv);
    cli.run()
}

// TODO: Original run_cli that used RuntimeCliDefaults is commented out
// pub fn run_cli(
//     argv: Vec<String>,
//     caller_type: baml_runtime::RuntimeCliDefaults,
// ) -> Result<ExitCode> {
//     let mut cli = commands::RuntimeCli::parse_from_smart(argv);
//     if !matches!(cli.command, commands::Commands::Test(_)) {
//         // We only need to set the exit handlers if we're not running tests
//         // and the caller is Python.

View on GitHub (pinned to bd85ce9dee)