install_cli fails under Rails: the CLI is written in text mode, as File::BINARY is a no-op outside Windows #177

bin/rails claude_agent_sdk:install_cli, the Docker build step docs/rails.md suggests, fails in a Rails app:

ClaudeAgentSDK::CLIInstallError: Failed to fetch https://downloads.claude.ai/claude-code-releases/2.1.295/linux-arm64/claude:
Encoding::UndefinedConversionError: "\xB7" from ASCII-8BIT to UTF-8

The installer writes the download to a file opened with File::WRONLY | File::CREAT | File::EXCL | File::BINARY (lib/claude_agent_sdk/cli_installer.rb, line 184 on main 532cbdf). File::BINARY only matters on Windows; elsewhere it is 0, so the file is opened in text mode. Rails sets Encoding.default_internal to UTF-8, and a text-mode write then converts each binary chunk to UTF-8, which fails on the first byte that is not valid UTF-8.

Without Rails, the same happens as soon as default_internal is set, on main (1.4.0), on macOS here:

require "claude_agent_sdk"
require "tmpdir"

[nil, Encoding::UTF_8].each do |internal|
  Encoding.default_internal = internal
  Dir.mktmpdir do |dir|
    path = ClaudeAgentSDK::CLIInstaller.install_pinned(dir: dir)
    puts "#{internal.inspect}: installed #{File.size(path) / 1_000_000} MB"
  rescue ClaudeAgentSDK::CLIInstallError => e
    puts "#{internal.inspect}: #{e.message}"
  end
end
p File::BINARY

nil: installed 239 MB
#<Encoding:UTF-8>: Failed to fetch https://downloads.claude.ai/claude-code-releases/2.1.295/darwin-arm64/claude: Encoding::UndefinedConversionError: "\xCF" from ASCII-8BIT to UTF-8
0

Calling file.binmode right after the File.open (or opening with binmode: true) would make the write binary on every platform. Until then, a Dockerfile can install the CLI outside Rails:

RUN ruby -rbundler/setup -rclaude_agent_sdk -e 'ClaudeAgentSDK::CLIInstaller.install_pinned(dir: "vendor/claude")'

Found in a Rails 8.1 app, Ruby 4.0, claude-agent-sdk 1.3.0; the code is the same on main.