gitbutlerapp/gitbutler · warning

Automatic CLI installation is not supported on Windows. To

Error message

Automatic CLI installation is not supported on Windows.

To use the But CLI, you have two options:

1. Copy the executable to a directory in your PATH:
copy "{}" "%LOCALAPPDATA%\Microsoft\WindowsApps\{}"

2. Add the current location to your PATH environment variable:
- Press the Win key and select 'System'
- Type 'Environment' into the search box and select 'edit variables for your account'
- Under 'User variables', select 'Path' and click 'Edit'
- Click 'New' and add: {}

After either option, restart your terminal to use the 'but' command.

What it means

On Windows, install_cli_windows never installs automatically: symlinks require developer mode or admin rights and there is no guaranteed user-writable PATH directory. It bails with a message giving two manual options - copy the exe into %LOCALAPPDATA%\Microsoft\WindowsApps, or add the binary's directory to the user PATH - and reminds the user to restart the terminal (crates/but-action/src/cli.rs:132).

Source

Thrown at crates/but-action/src/cli.rs:132

        return Ok(());
    }
    bail!("Run `CARGO_TARGET_DIR=$PWD/target/tauri cargo build -p but` to build the `but` binary")
}

/// On Windows, we'll provide helpful instructions rather than attempt automatic installation
/// since:
/// 1. Creating symlinks requires developer mode or admin privileges
/// 2. There's no standard user-writable directory that's always in PATH
/// 3. Users typically add directories to PATH manually on Windows
///
/// Note that this isn't usually called on Windows.
#[cfg(windows)]
fn install_cli_windows(cli_path: std::path::PathBuf) -> anyhow::Result<()> {
    let but_filename = cli_path
        .file_name()
        .context("BUG: encountered but CLI path without /")?;

    bail!(
        "Automatic CLI installation is not supported on Windows.\n\
        \n\
        To use the But CLI, you have two options:\n\
        \n\
        1. Copy the executable to a directory in your PATH:\n\
           copy \"{}\" \"%LOCALAPPDATA%\\Microsoft\\WindowsApps\\{}\"\n\
        \n\
        2. Add the current location to your PATH environment variable:\n\
           - Press the Win key and select 'System'\n\
           - Type 'Environment' into the search box and select 'edit variables for your account'\n\
           - Under 'User variables', select 'Path' and click 'Edit'\n\
           - Click 'New' and add: {}\n\
        \n\
        After either option, restart your terminal to use the 'but' command.",
        cli_path.display(),
        but_filename.display(),
        cli_path
            .parent()

View on GitHub (pinned to caf1f223d3)

Solutions

1. Option 1: copy the exe - `copy "<cli_path>" "%LOCALAPPDATA%\Microsoft\WindowsApps\but.exe"` in cmd (mkdir the folder if missing)
2. Option 2: add the binary's directory to the user Path variable via 'Edit environment variables for your account', new entry pointing at the folder containing but.exe
3. Restart the terminal and verify with `but --version`

Example fix

:: before: invoking install on Windows -> bail with instructions
:: after: manual copy, then verify
cmd> copy "C:\path\to\target\tauri\but.exe" "%LOCALAPPDATA%\Microsoft\WindowsApps\but.exe
cmd> but --version

// Route around automatic install on Windows before it bails
#[cfg(windows)]
{
    show_manual_windows_instructions(&cli_path); // copy-to-WindowsApps or PATH guidance
    return Ok(());
}
#[cfg(not(windows))]
do_install_cli(mode)?;

When it happens

Trigger: Calling do_install_cli on Windows (note the code remarks this is unusual - the UI normally shows the instructions directly); a build where the cfg(windows) routing reaches install_cli_windows.

Common situations: Windows users clicking 'install CLI'; automated flows calling the install action on a Windows host.

Related errors

• Refusing to install symlink onto existing non-symlink at '{U
• Run `CARGO_TARGET_DIR=$PWD/target/tauri cargo build -p but`
• Failed to parse diff header
• BUG: It should not be possible to omit sources
• implement list and call recursively

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/b0b1cc281934ac53. Report an issue: GitHub.