What causes "CLI installation from the app is only supported on macOS" in gitbutlerapp/gitbutler?

Install the CLI manually per the instructions in Settings

CLI installation from the app is only supported on macOS

Error message

CLI installation from the app is only supported on macOS

What it means

install_cli_v2, the newer CLI installation entry point, is only implemented for macOS. On non-macOS platforms the parameters are ignored and the function bails, telling users installation from the app is macOS-only and manual steps are required.

Solutions

Install the CLI manually per the instructions in Settings
Hide the install action on non-macOS platforms
Use the platform's own package manager or symlink the binary yourself

Defensive patterns

Strategy: validation

Validate before calling

if (process.platform !== 'darwin') {
  showManualInstallInstructions();
} else {
  await installCliV2(cliPath, policy);
}

Try / catch

try {
  await installCliV2(cliPath, policy);
} catch (e) {
  if (String(e).includes('only supported on macOS')) {
    openManualInstallDocs();
  } else throw e;
}

Prevention

Gate v2 install UI to darwin builds
Document manual installation for Linux/Windows users
Add platform checks in the command layer, not just UI

When it happens

Trigger: Calling install_cli_v2(cli_path, symlink_policy) on a non-macOS platform.

Common situations: Desktop app running on Linux/Windows invoking the v2 install API; CLI setup flows not gated by OS.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/cb181c2f08e5993a. Report an issue: GitHub.

Appendix: source

Thrown at crates/but-api/src/legacy/cli.rs:58

            symlink_policy,
        ) {
            Ok(()) => Ok(true),
            Err(err)
                if err
                    .downcast_ref::<but_error::Context>()
                    .is_some_and(|context| {
                        matches!(context.code, but_error::Code::CliInstallCancelled)
                    }) =>
            {
                Ok(false)
            }
            Err(err) => Err(err),
        }
    }
    #[cfg(not(target_os = "macos"))]
    {
        let _ = (cli_path, symlink_policy);
        anyhow::bail!("CLI installation from the app is only supported on macOS")
    }
}

#[but_api]
#[instrument(err(Debug))]
pub fn cli_path() -> Result<String> {
    let cli_path = get_cli_path()?;
    Ok(cli_path.to_string_lossy().to_string())
}

View on GitHub (pinned to 58e5313667)