feat: support locally provided CLI binaries via binaryDestination (#286)

The existing CLI resolution logic hardcodes the CLI name based on the OS
and architecture without any flexibility in specifying an existing CLI.
It has a couple of options to specify the download dir (binDir and
dataDir) but not the CLI name. This PR revolves around the bindDir
setting which is now renamed to binaryDestination and it allows users to
specify an absolute path to an existing executable filename or a
destination dir. If the user specifies the destination dir then the CLI
name will use the existing default name based on the os and
architecture.

In addition a couple of windows tests were refactored because they
required git bash utilities to be installed on Windows. Recent builds on
the Github CI failed because commands like `printf` were not available.
A lot of UTs were also added to cover the behavior of CLI resolution
when based on how binaryDestination, dataDir, enableDownloads and
enableFallback flags are configured. Now there is also a special section
in the README detailing the CLI resolution algorithm.

By and large we tried to keep the existing behavior without breaking
compatibility for existing users who were supposed to configure a folder
in the binaryDir.

The new behavior works like this:
```
1. Look at the binaryDestination, and if it points to an existing executable file check it if it's version matches server version:
    1.1 If it matches then return it.
    1.2 If it doesn't match then check whether downloads are enabled
        1.2.1 if it is enabled then download the server version of CLI and overwrite the one at binaryDestination
        1.2.2 if it is not enabled then check `$dataDir/$hostname/coder-$os-$arch.$ext
               1.2.2.1 if the CLI in the dataDir exists and matches, then return it.
                1.2.2.1 otherwise prefer the CLI from binaryDestination over the one from dataDir
2. If binaryDestination points to a directory, check $binDestination/$hostname/coder-$os-$arch.$ext if it's version matches server version:
    2.1 If it matches then return it.
    2.2 If it doesn't match then check whether downloads are enabled
        2.2.1 if it is enabled then download the server version of CLI and overwrite the one at $binDestination/$hostname/coder-$os-$arch.$ext 
        2.2.2 if it is not enabled then check `$dataDir/$hostname/coder-$os-$arch.$ext
               2.2.2.1 if the CLI in the dataDir exists and matches, then return it.
                2.2.2.1 otherwise prefer the CLI from $binDestination/$hostname/coder-$os-$arch.$ext  over the one from dataDir
```

- resolves #285

Author: fioan89

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+
+- support for using a locally provided CLI binary when downloads are disabled
+
 ## 0.8.6 - 2026-03-05
 
 ### Changed

README.md

@@ -448,15 +448,18 @@ storage paths. The options can be configured from the plugin's main Workspaces p
   If a relative path is provided, it is resolved against the deployment domain.
 
 - `Enable downloads` allows automatic downloading of the CLI if the current version is missing or outdated.
+  Defaults to enabled.
 
-- `Binary directory` specifies the directory where CLI binaries are stored. If omitted, it defaults to the data
-  directory.
+- `Binary destination` specifies where the CLI binary is placed. This can be a path to an existing
+  executable (used as-is) or a base directory (the CLI is placed under a host-specific subdirectory).
+  If blank, the data directory is used. Supports `~` and `$HOME` expansion.
 
-- `Enable binary directory fallback` if enabled, falls back to the data directory when the specified binary
-  directory is not writable.
+- `Enable binary directory fallback` when enabled, if the binary destination is not writable the
+  plugin falls back to the data directory instead of failing. Only takes effect when downloads are
+  enabled and the binary destination differs from the data directory. Defaults to disabled.
 
-- `Data directory` directory where plugin-specific data such as session tokens and binaries are stored if not
-  overridden by the binary directory setting.
+- `Data directory` directory where deployment-specific data such as session tokens and CLI binaries
+  are stored. Each deployment gets a host-specific subdirectory (e.g. `coder.example.com`).
 
 - `Header command` command that outputs additional HTTP headers. Each line of output must be in the format key=value.
   The environment variable CODER_URL will be available to the command process.
@@ -471,6 +474,24 @@ storage paths. The options can be configured from the plugin's main Workspaces p
   Helpful for customers that have their own in-house dashboards. Defaults to the Coder deployment templates page.
   This setting supports `$workspaceOwner` as placeholder with the replacing value being the username that logged in.
 
+#### How CLI resolution works
+
+When connecting to a deployment the plugin ensures a compatible CLI binary is available.
+The settings above interact as follows:
+
+1. If a CLI already exists at the binary destination and its version matches the deployment, it is
+   used immediately.
+2. If **downloads are enabled**, the plugin downloads the matching version to the binary destination.
+    - If the download fails with a permission error and **binary directory fallback** is enabled (and
+      the binary destination is not already in the data directory), the plugin checks whether the data
+      directory already has a matching CLI. If so it is used; otherwise the plugin downloads to the
+      data directory instead.
+    - Any other download error is reported to the user.
+3. If **downloads are disabled**, the plugin checks the data directory for a CLI whose version
+   matches the deployment. If no exact match is found anywhere, whichever CLI is available is
+   returned — preferring the binary destination unless it is missing, in which case the data
+   directory CLI is used regardless of its version. If no CLI exists at all, an error is raised.
+
 ### TLS settings
 
 The following options control the secure communication behavior of the plugin with Coder deployment and its available

gradle.properties

@@ -1,3 +1,3 @@
-version=0.8.6
+version=0.8.7
 group=com.coder.toolbox
 name=coder-toolbox

src/main/kotlin/com/coder/toolbox/cli/CoderCLIManager.kt

@@ -50,14 +50,22 @@ internal data class Version(
 /**
  * Do as much as possible to get a valid, up-to-date CLI.
  *
- * 1. Read the binary directory for the provided URL.
- * 2. Abort if we already have an up-to-date version.
- * 3. Download the binary using an ETag.
- * 4. Abort if we get a 304 (covers cases where the binary is older and does not
- *    have a version command).
- * 5. Download on top of the existing binary.
- * 6. Since the binary directory can be read-only, if downloading fails, start
- *    from step 2 with the data directory.
+ * 1. Create a CLI manager for the deployment URL.
+ * 2. If the CLI version matches the build version, return it immediately.
+ * 3. If downloads are enabled, attempt to download the CLI.
+ *    a. On success, return the CLI.
+ *    b. On [java.nio.file.AccessDeniedException]: rethrow if the binary
+ *       path parent equals the data directory or if binary directory
+ *       fallback is disabled. Otherwise, if the fallback data directory
+ *       CLI already matches the build version return it; if not, download
+ *       to the data directory and return the fallback CLI.
+ *    c. Any other exception propagates to the caller.
+ * 4. If downloads are disabled:
+ *    a. If the data directory CLI version matches, return it.
+ *    b. If neither the configured binary nor the data directory CLI can
+ *       report a version, throw [IllegalStateException].
+ *    c. Prefer the configured binary; fall back to the data directory CLI
+ *       only when the configured binary is missing or unexecutable.
  */
 suspend fun ensureCLI(
     context: CoderToolboxContext,
@@ -97,6 +105,17 @@ suspend fun ensureCLI(
             if (binPath.parent == dataDir || !settings.enableBinaryDirectoryFallback) {
                 throw e
             }
+            // fall back to the data directory.
+            val fallbackCLI = CoderCLIManager(context, deploymentURL, true)
+            val fallbackMatches = fallbackCLI.matchesVersion(buildVersion)
+            if (fallbackMatches == true) {
+                reportProgress("Local CLI version from data directory matches server version: $buildVersion")
+                return fallbackCLI
+            }
+
+            reportProgress("Downloading Coder CLI to the data directory...")
+            fallbackCLI.download(buildVersion, showTextProgress)
+            return fallbackCLI
         }
     }
 
@@ -108,14 +127,11 @@ suspend fun ensureCLI(
         return dataCLI
     }
 
-    if (settings.enableDownloads) {
-        reportProgress("Downloading Coder CLI to the data directory...")
-        dataCLI.download(buildVersion, showTextProgress)
-        return dataCLI
-    }
-
     // Prefer the binary directory unless the data directory has a
     // working binary and the binary directory does not.
+    if (cliMatches == null && dataCLIMatches == null && !settings.enableDownloads) {
+        throw IllegalStateException("Can't resolve Coder CLI and downloads are disabled")
+    }
     return if (cliMatches == null && dataCLIMatches != null) dataCLI else cli
 }
 

src/main/kotlin/com/coder/toolbox/settings/ReadOnlyCoderSettings.kt

@@ -35,10 +35,13 @@ interface ReadOnlyCoderSettings {
     val binarySource: String?
 
     /**
-     * Directories are created here that store the CLI for each domain to which
-     * the plugin connects.   Defaults to the data directory.
+     * An absolute path to either a directory or an existing executable CLI binary.
+     * When the path points to an existing executable file, it is used as the CLI
+     * binary path directly. Otherwise, it is treated as a base directory under
+     * which the CLI is placed in a host-specific subdirectory. Defaults to the
+     * data directory when not set.
      */
-    val binaryDirectory: String?
+    val binaryDestination: String?
 
     /**
      * Controls whether we verify the cli signature
@@ -60,19 +63,14 @@ interface ReadOnlyCoderSettings {
      */
     val defaultCliBinaryNameByOsAndArch: String
 
-    /**
-     * Configurable CLI binary name with extension, dependent on OS and arch
-     */
-    val binaryName: String
-
     /**
      * Default CLI signature name based on OS and architecture
      */
     val defaultSignatureNameByOsAndArch: String
 
     /**
      * Where to save plugin data like the Coder binary (if not configured with
-     * binaryDirectory) and the deployment URL and session token.
+     * binaryDestination) and the deployment URL and session token.
      */
     val dataDirectory: String?
 

src/main/kotlin/com/coder/toolbox/store/CoderSettingsStore.kt

@@ -41,15 +41,14 @@ class CoderSettingsStore(
     override val defaultURL: String get() = store[DEFAULT_URL] ?: "https://dev.coder.com"
     override val useAppNameAsTitle: Boolean get() = store[APP_NAME_AS_TITLE]?.toBooleanStrictOrNull() ?: false
     override val binarySource: String? get() = store[BINARY_SOURCE]
-    override val binaryDirectory: String? get() = store[BINARY_DIRECTORY]
+    override val binaryDestination: String? get() = store[BINARY_DESTINATION] ?: store[BINARY_DIRECTORY]
     override val disableSignatureVerification: Boolean
         get() = store[DISABLE_SIGNATURE_VALIDATION]?.toBooleanStrictOrNull() ?: false
     override val fallbackOnCoderForSignatures: SignatureFallbackStrategy
         get() = SignatureFallbackStrategy.fromValue(store[FALLBACK_ON_CODER_FOR_SIGNATURES])
     override val httpClientLogLevel: HttpLoggingVerbosity
         get() = HttpLoggingVerbosity.fromValue(store[HTTP_CLIENT_LOG_LEVEL])
     override val defaultCliBinaryNameByOsAndArch: String get() = getCoderCLIForOS(getOS(), getArch())
-    override val binaryName: String get() = store[BINARY_NAME] ?: getCoderCLIForOS(getOS(), getArch())
     override val defaultSignatureNameByOsAndArch: String get() = getCoderSignatureForOS(getOS(), getArch())
     override val dataDirectory: String? get() = store[DATA_DIRECTORY]
     override val globalDataDirectory: String get() = getDefaultGlobalDataDir().normalize().toString()
@@ -124,21 +123,37 @@ class CoderSettingsStore(
     }
 
     /**
-     * To where the specified deployment should download the binary.
+     * To where the specified deployment should place the CLI binary.
+     *
+     * Resolution logic:
+     * 1. If [binaryDestination] is null/blank, return the deployment's data
+     *    directory with the default CLI binary name. [forceDownloadToData]
+     *    is ignored because both paths resolve to the same location.
+     * 2. If [forceDownloadToData] is true, return a host-specific subdirectory
+     *    under the deployment's data directory with the default CLI binary name.
+     * 3. If the expanded (~ and $HOME) [binaryDestination] is an existing executable file,
+     *    return it as-is.
+     * 4. Otherwise, treat [binaryDestination] as a base directory and return a
+     *    host-specific subdirectory with the default CLI binary name.
      */
     override fun binPath(
         url: URL,
         forceDownloadToData: Boolean,
     ): Path {
-        binaryDirectory.let {
-            val dir =
-                if (forceDownloadToData || it.isNullOrBlank()) {
-                    dataDir(url)
-                } else {
-                    withHost(Path.of(expand(it)), url)
-                }
-            return dir.resolve(binaryName).toAbsolutePath()
+        if (binaryDestination.isNullOrBlank()) {
+            return dataDir(url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
+        }
+
+        val dest = Path.of(expand(binaryDestination!!))
+        val isExecutable = Files.isRegularFile(dest) && Files.isExecutable(dest)
+
+        if (forceDownloadToData) {
+            return dataDir(url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
+        }
+        if (isExecutable) {
+            return dest.toAbsolutePath()
         }
+        return withHost(dest, url).resolve(defaultCliBinaryNameByOsAndArch).toAbsolutePath()
     }
 
     /**
@@ -179,8 +194,8 @@ class CoderSettingsStore(
         store[BINARY_SOURCE] = source
     }
 
-    fun updateBinaryDirectory(dir: String) {
-        store[BINARY_DIRECTORY] = dir
+    fun updateBinaryDestination(dest: String) {
+        store[BINARY_DESTINATION] = dest
     }
 
     fun updateDataDirectory(dir: String) {

src/main/kotlin/com/coder/toolbox/store/StoreKeys.kt

@@ -10,16 +10,17 @@ internal const val APP_NAME_AS_TITLE = "useAppNameAsTitle"
 
 internal const val BINARY_SOURCE = "binarySource"
 
+@Deprecated("Use BINARY_DESTINATION instead", replaceWith = ReplaceWith("BINARY_DESTINATION"))
 internal const val BINARY_DIRECTORY = "binaryDirectory"
 
+internal const val BINARY_DESTINATION = "binaryDestination"
+
 internal const val DISABLE_SIGNATURE_VALIDATION = "disableSignatureValidation"
 
 internal const val FALLBACK_ON_CODER_FOR_SIGNATURES = "signatureFallbackStrategy"
 
 internal const val HTTP_CLIENT_LOG_LEVEL = "httpClientLogLevel"
 
-internal const val BINARY_NAME = "binaryName"
-
 internal const val DATA_DIRECTORY = "dataDirectory"
 
 internal const val ENABLE_DOWNLOADS = "enableDownloads"

src/main/kotlin/com/coder/toolbox/views/CoderSettingsPage.kt

@@ -38,8 +38,8 @@ class CoderSettingsPage(
     // TODO: Copy over the descriptions, holding until I can test this page.
     private val binarySourceField =
         TextField(context.i18n.ptrl("Binary source"), settings.binarySource ?: "", TextType.General)
-    private val binaryDirectoryField =
-        TextField(context.i18n.ptrl("Binary directory"), settings.binaryDirectory ?: "", TextType.General)
+    private val binaryDestinationField =
+        TextField(context.i18n.ptrl("Binary destination"), settings.binaryDestination ?: "", TextType.General)
     private val dataDirectoryField =
         TextField(context.i18n.ptrl("Data directory"), settings.dataDirectory ?: "", TextType.General)
     private val enableDownloadsField =
@@ -131,7 +131,7 @@ class CoderSettingsPage(
             binarySourceField,
             enableDownloadsField,
             useAppNameField,
-            binaryDirectoryField,
+            binaryDestinationField,
             enableBinaryDirectoryFallbackField,
             disableSignatureVerificationField,
             signatureFallbackStrategyField,
@@ -156,7 +156,7 @@ class CoderSettingsPage(
             Action(context, "Save", closesPage = true) {
                 with(context.settingsStore) {
                     updateBinarySource(binarySourceField.contentState.value)
-                    updateBinaryDirectory(binaryDirectoryField.contentState.value)
+                    updateBinaryDestination(binaryDestinationField.contentState.value)
                     updateDataDirectory(dataDirectoryField.contentState.value)
                     updateEnableDownloads(enableDownloadsField.checkedState.value)
                     updateUseAppNameAsTitle(useAppNameField.checkedState.value)
@@ -200,8 +200,8 @@ class CoderSettingsPage(
         binarySourceField.contentState.update {
             settings.binarySource ?: ""
         }
-        binaryDirectoryField.contentState.update {
-            settings.binaryDirectory ?: ""
+        binaryDestinationField.contentState.update {
+            settings.binaryDestination ?: ""
         }
         dataDirectoryField.contentState.update {
             settings.dataDirectory ?: ""

src/main/resources/localization/defaultMessages.po

@@ -70,7 +70,7 @@ msgstr ""
 msgid "Binary source"
 msgstr ""
 
-msgid "Binary directory"
+msgid "Binary destination"
 msgstr ""
 
 msgid "Data directory"