jdx/mise · error

{flag} cannot be used with a bootstrap subcommand

Error message

{flag} cannot be used with a bootstrap subcommand

What it means

This error is thrown by mise's `bootstrap` command when a mutually exclusive combination of flags is passed: `--adopt` or `--from` together with a bootstrap subcommand (e.g. `mise bootstrap dotfiles pull --from ...`). The flags only make sense for the bare `mise bootstrap` flow, so the CLI refuses the invocation rather than guessing intent.

Source

Thrown at src/cli/bootstrap.rs:1316

        self.dry_run |= dry_run;
        self.yes |= yes;
    }

    #[cfg(test)]
    pub(super) fn inherited_root_flags(&self) -> (bool, bool) {
        (self.dry_run, self.yes)
    }

    pub(crate) async fn run(mut self) -> Result<()> {
        normalize_adopt_alias(&mut self.adopt, self.from_git.take());
        if self.from.is_some() || self.adopt.is_some() {
            if self.command.is_some() {
                let flag = if self.adopt.is_some() {
                    "--adopt"
                } else {
                    "--from"
                };
                bail!("{flag} cannot be used with a bootstrap subcommand");
            }
            return self.run_from().await;
        }
        if let Some(command) = self.command.take() {
            return command.run().await;
        }
        let generation = OperationScope::begin("bootstrap", self.dry_run).await?;
        let result = self.run_phases().await;
        generation.refresh_tracked().await;
        let error = result.as_ref().err().map(|err| format!("{err:#}"));
        generation.finish(error, result.as_ref().ok().cloned());
        // a complete run applied the declarations that arrived through
        // sync; a declined, partial, or dry run did not
        if let Ok(summary) = &result
            && !self.dry_run
            && !is_declined(summary)
            && self.only.is_empty()
            && self.skip.is_empty()

View on GitHub (pinned to afd2eddd3a)

Solutions

  1. Remove the subcommand so the flags apply to the bare `mise bootstrap` flow (e.g. `mise bootstrap --from <repo>` or `mise bootstrap --adopt`).
  2. Remove `--adopt`/`--from` if you actually meant to run a bootstrap subcommand (e.g. `mise bootstrap dotfiles pull`).
  3. Check `mise bootstrap --help` to see which flags belong to the top-level command vs the subcommands.
  4. If scripting, split the invocation: run the bare bootstrap with flags once, then invoke subcommands separately.

Example fix

// before
mise bootstrap dotfiles pull --from git@github.com:me/dotfiles.git
// after
mise bootstrap --from git@github.com:me/dotfiles.git
mise bootstrap dotfiles pull
Defensive patterns

Strategy: validation

Validate before calling

# shell pre-check before invoking
if [[ -n "$BOOTSTRAP_FROM" && -n "$BOOTSTRAP_SUBCMD" ]]; then
  echo "--from/--adopt cannot be combined with a bootstrap subcommand" >&2; exit 1
fi

Try / catch

mise bootstrap --from "$REPO" || mise bootstrap "$SUBCMD"  # run as separate invocations, not one

Prevention

When it happens

Trigger: Running `mise bootstrap` with `--adopt` (or `--from <repo>`) while also naming a subcommand as a positional argument; `self.command.is_some()` is true and `self.adopt`/`self.from` are set, so the bail fires before dispatching to `run_from` or the subcommand.

Common situations: Copying a bootstrap invocation that used `--from` and appending a subcommand like `dotfiles pull` or `status`; scripting `mise bootstrap --adopt <subcommand>` assuming the flag applies to all subcommands; shell aliases that bake in `--adopt` or `--from`.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/6a535a802ebe8393. Report an issue: GitHub.