hermes-ice/homelab/raw/articles/forge/reference/docs-forge-bin.md

type, agent, source, scraped, content_hash

type	agent	source	scraped	content_hash
agent-doc	ForgeCode	https://forgecode.dev/docs/forge-bin/	2026-04-28T21:02:19.300082+00:00	520e6a0a

$FORGE_BIN

When you install ForgeCode normally, the binary lands in your $PATH as forge. The ZSH plugin assumes that name and calls it directly. That works until it doesn't — when you're testing a local build, running a binary at an absolute path, or keeping multiple versions side by side.

FORGE_BIN lets you tell the ZSH plugin exactly which binary to use instead.

What It Controls​

The ZSH plugin sources its shell integration at startup:

source <($FORGE_BIN extension zsh)

Every time you invoke ForgeCode from the shell, $FORGE_BIN is the command that runs. Change it and you change which binary answers.

The default is forge — whatever which forge resolves to on your system.

When to Change It​

Local build from source. You've compiled ForgeCode locally and want to test your changes without installing the binary system-wide:

export FORGE_BIN=/path/to/forgecode/target/debug/forge

Non-standard install path. The binary is on disk but not in a directory on your $PATH:

export FORGE_BIN=/opt/forgecode/bin/forge

Multiple versions. You have a stable release as forge and want to test a nightly build without replacing it:

export FORGE_BIN=~/bin/forge-nightly

In each case, the ZSH plugin picks up the change and routes every invocation through the specified binary.

Setting It​

~/.zshrc — persistent

This is the right place for FORGE_BIN. It must be set before the ZSH plugin is sourced, so it belongs in your shell profile rather than ~/.env:

# ~/.zshrcexport FORGE_BIN=/path/to/your/forge# This line sources the ZSH integration using $FORGE_BINsource <($FORGE_BIN extension zsh)

Reload your shell after editing:

source ~/.zshrc

Current session — temporary

To switch binaries for just the current terminal session:

export FORGE_BIN=~/builds/forge-devsource <($FORGE_BIN extension zsh)

The change disappears when the session ends. This is useful for one-off testing without touching your permanent configuration.

Verifying the Change​

After setting FORGE_BIN, confirm the right binary is being used:

echo $FORGE_BIN          # shows the path you set$FORGE_BIN --version     # confirms the binary responds and shows its version

If $FORGE_BIN --version fails, the path is wrong or the binary isn't executable. Double-check the path and run chmod +x $FORGE_BIN if needed.

Reverting to the Default​

Unset the variable to go back to the system-installed forge:

unset FORGE_BINsource <(forge extension zsh)

Or remove the export FORGE_BIN=... line from your ~/.zshrc and reload.

For everything else the ZSH integration can do — agent selection, multiline input, file tagging — see the ZSH Support reference.