install: documented env vars are ignored by script, flags are undocumented, PATH modification is forced

Summary

The install script has a documentation/implementation mismatch: the README documents environment variables (OPENCODE_INSTALL_DIR, XDG_BIN_DIR) that the script never checks, while the flags the script does support (--no-modify-path, --help, --version, --binary) are not documented anywhere in the README or docs site.

Additionally, the script forces PATH modification into shell config files (.zshrc, .bashrc, etc.) by default. While --no-modify-path exists to opt out, this is undiscoverable without reading the source.

Details

1. Documented env vars that do nothing

The README "Installation Directory" section states:

The install script respects the following priority order for the installation path:

1. $OPENCODE_INSTALL_DIR - Custom installation directory
2. $XDG_BIN_DIR - XDG Base Directory Specification compliant path
3. $HOME/bin - Standard user binary directory (if it exists or can be created)
4. $HOME/.opencode/bin - Default fallback

However, the script hardcodes the install directory at the top:

INSTALL_DIR=$HOME/.opencode/bin
mkdir -p "$INSTALL_DIR"

Neither OPENCODE_INSTALL_DIR, XDG_BIN_DIR, nor $HOME/bin are referenced anywhere in the script. Running OPENCODE_INSTALL_DIR=/usr/local/bin curl ... | bash silently installs to ~/.opencode/bin as usual.

2. Existing flags are undocumented

The script supports four flags via argument parsing:

Flag	Purpose
-h, --help	Display usage information
-v, --version <ver>	Install a specific version
-b, --binary <path>	Install from a local binary
--no-modify-path	Don't modify shell config files

None of these appear in the README installation section or the docs site. The only way to discover them is by running --help or reading the source. The --no-modify-path flag in particular addresses real user needs (NixOS/home-manager, immutable distros, dotfile managers -- see #5884) but is invisible to anyone who doesn't dig into the code.

3. Forced PATH modification as default behavior

The script appends export PATH=... to shell config files (.zshrc, .bashrc, .bash_profile, etc.) without prompting. It picks the first config file it finds that matches the current shell and writes to it.

This has been reported repeatedly as a friction point:

• #13403 -- installer doesn't prompt users to source the file after modifying it
• #13764 -- request to add source instructions
• #18624 -- same, still open
• #17132 -- writes to .bashrc on macOS instead of .bash_profile
• #8512 -- doesn't respect $ZDOTDIR

The --no-modify-path flag exists but is undiscoverable.

Suggested

• Remove OPENCODE_INSTALL_DIR / XDG_BIN_DIR from the README, or implement them in the script
• Document the existing flags (--no-modify-path, --help, --version, --binary) in the README and docs site
• Consider making PATH modification opt-in rather than opt-out, or at minimum print source/restart instructions after modification

Environment

• OS: Ubuntu 26.04 (WSL)
• Install method: curl -fsSL https://opencode.ai/install | bash
• Script version: v1.18.29