Skip to content

feat: support locally provided CLI binaries via binaryDestination#286

Open
fioan89 wants to merge 12 commits intomainfrom
impl-support-for-local-cli
Open

feat: support locally provided CLI binaries via binaryDestination#286
fioan89 wants to merge 12 commits intomainfrom
impl-support-for-local-cli

Conversation

@fioan89
Copy link
Copy Markdown
Collaborator

@fioan89 fioan89 commented Mar 23, 2026

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

fioan89 added 3 commits March 23, 2026 23:50
Reimplemented `binPath` to support three modes:
- default data directory
- absolute path to a pre-existing local CLI (when downloads are disabled)
- and base directory with host-specific subdirectory (when downloads are enabled)

This modes are controlled by the Binary directory setting now renamed to
Binary destination and the enable downloads setting.

- resolves #285
That tests the fallback configuration from binaryDestination
to the deprecated binaryDirectory.
In addition, the existing tests were updated as they now have to
take into account that enableDownloads option affects the output
of binPath API.
@fioan89 fioan89 requested review from code-asher and matifali March 24, 2026 20:26
Windows needs special handling because we can't mock
the exe binary as a bash script like we do on Linux/Mac.
In addition, there were a couple of unix paths hardcoded
in some of the tests.
fioan89 added 7 commits March 25, 2026 22:04
Windows needs special handling because we can't mock
the exe binary as a bash script like we do on Linux/Mac.
In addition, there were a couple of unix paths hardcoded
in some of the tests.
binaryDestination can now take a path to an executable or a path to a download directory.
In order to reflect the new behavior regarding CLI resolution in
general and the binary destination in particular.
Adds a chapter describing the behavior of binaryDestination,
dataDir, enableDownloads, and enableBinaryDirFallback, and
explains how these settings interact and work together.
Refactored some of the existing tests into a new
battery with a bunch additional tests to cover the complex
and intertwined way of working for binaryDestination, enableDownloads,
dataDir and enableFallback settings in the way CLI is resolved.
@matifali matifali removed their request for review March 28, 2026 20:54
Without GIT bash utilities installed. To remove the dependency
I duplicated some of the tests and used Windows commands only.
@fioan89 fioan89 requested review from EhabY and code-asher March 30, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

If coder is installed via winget, local binary fallback fails because plugin expects release artifact name instead of installed executable name

2 participants