Automatic CLI installation is only supported on macOS. See…

Error message

Automatic CLI installation is only supported on macOS. See Settings for manual installation instructions.

What it means

The install_cli API only implements automatic CLI symlink installation on macOS (where it can use privileged helper / trusted hosts). On any other platform it immediately bails with this message, directing users to manual installation via the app Settings.

Solutions

Use manual installation: follow the CLI setup instructions in the app Settings
Only expose/call the automatic install action on macOS builds
Feature-gate the install UI by target OS

Example fix

// before
await installCli();
// after
if (platform === 'darwin') {
  await installCli();
} else {
  openSettingsCliInstructions();
}

Defensive patterns

Strategy: validation

Validate before calling

if (navigator.platform !== 'MacIntel' && !navigator.userAgent.includes('Mac')) {
  showManualInstallInstructions();
} else {
  await installCli();
}

Try / catch

try {
  await installCli();
} catch (e) {
  if (String(e).includes('only supported on macOS')) {
    openSettingsCliInstructions();
  } else throw e;
}

Prevention

Feature-gate automatic CLI install behind an OS check
Always provide a manual-install path in Settings
Test install flows on all supported platforms

When it happens

Trigger: Calling install_cli() on Windows, Linux, or any non-macOS target (the #[cfg(not(target_os = "macos"))] branch).

Common situations: User clicks 'Install CLI' in the desktop app on Linux/Windows; automated tests exercising the install endpoint on non-macOS CI runners.

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

Appendix: source

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

use but_api_macros::but_api;
use tracing::instrument;

#[cfg(feature = "export-schema")]
but_schemars::register_sdk_type!(ExistingSymlinkPolicy);

#[but_api]
#[instrument(err(Debug))]
pub fn install_cli() -> Result<()> {
    #[cfg(target_os = "macos")]
    {
        but_action::cli::do_install_cli_v2(
            &get_cli_path()?,
            InstallMode::AllowPrivilegeElevation,
            ExistingSymlinkPolicy::Replace,
        )
    }
    #[cfg(not(target_os = "macos"))]
    anyhow::bail!(
        "Automatic CLI installation is only supported on macOS. See Settings for manual installation instructions."
    )
}

/// Install the bundled macOS CLI. Trusted hosts supply the source path, not renderers.
/// Returns false when administrator authorization is cancelled.
#[but_api(napi)]
#[instrument(err(Debug))]
pub fn install_cli_v2(cli_path: String, symlink_policy: ExistingSymlinkPolicy) -> Result<bool> {
    #[cfg(target_os = "macos")]
    {
        match but_action::cli::do_install_cli_v2(
            std::path::Path::new(&cli_path),
            InstallMode::AllowPrivilegeElevation,
            symlink_policy,
        ) {
            Ok(()) => Ok(true),
            Err(err)

View on GitHub (pinned to 58e5313667)