Skip to main content

Installation

Pre-release beta

The Forge CLI is currently distributed as a pre-release beta. The npm package is published under the beta dist-tag (@cdx-forge/cli@beta) and the Homebrew tap installs the latest beta tarball. Until GA, expect breaking changes between betas — pin to a specific version in CI/CD.

The Forge CLI can be installed via Homebrew or npm/pnpm. Choose the method that best suits your workflow.

Prerequisites​

Before installing the Forge CLI, ensure you have the following:

  • Node.js >= 18 (download)
  • Git (for widget scaffolding and PR features)
  • Docker (for the OLB playground and OIDC Toolkit — Docker Desktop on macOS/Windows)
  • Developer Console account with an Admin or Developer role

For submission and PR features, you also need:

  • GitHub CLI — brew install gh (github.com/cli/cli)
  • GitHub access to the dfh-candescent-extensions organization (after accepting a collaborator invitation)

Mobile Preview Prerequisites​

If you plan to preview widgets or Aspects on mobile, you will also need:

  • Expo Go installed on a physical iOS or Android device, or
  • iOS Simulator (via Xcode on macOS) and/or Android Emulator (via Android Studio)
  • Same Wi-Fi network — your phone and your development machine must be on the same network for Metro Bundler to reach your device. If you need cross-network access (e.g., your phone on cellular), use Expo's tunnel mode (npx expo start --tunnel)
important

The iPhone Camera app does not handle exp:// URLs. Use the Expo Go app's built-in QR scanner to open mobile previews, or press i/a in the Metro terminal to launch a simulator.

Homebrew (macOS / Linux)​

The recommended installation method for macOS and Linux:

Bash
brew tap candescent-dev/forge
brew install forge-cli

Verify the installation:

Bash
forge --version
forge --help

To upgrade:

Bash
brew update
brew upgrade forge-cli

To uninstall:

Bash
brew uninstall forge-cli
brew untap candescent-dev/forge

The Forge CLI formula files live in the public GitHub repository candescent-dev/homebrew-forge. That repository is what Homebrew clones when you run brew tap candescent-dev/forge; it is not itself “the tap” in Homebrew’s sense, but the source repo for that tap. Pre-built tarballs are signed and attached to GitHub Releases in that same repository by the CLI release automation on every release.

npm / pnpm (All Platforms)​

Install globally with pnpm (recommended) or npm:

Bash
# pnpm (recommended)
pnpm add -g @cdx-forge/cli

# npm
npm install -g @cdx-forge/cli

Verify the installation:

Bash
forge --version
forge --help

To upgrade:

Bash
pnpm update -g @cdx-forge/cli
# or: npm update -g @cdx-forge/cli

The package is published to the public npm registry as @cdx-forge/cli by an automated GitHub Actions workflow on every release.

Shell Autocomplete​

The CLI supports tab completion for commands, flags, flag values (template names, platforms), and dynamic widget/Aspect names.

zsh (default on macOS)​

Bash
forge autocomplete zsh     # generates completions and adds a source line to ~/.zshrc
rm -f ~/.zcompdump*        # clear the stale zsh completions cache
exec zsh                   # restart shell to pick up new completions

bash​

Bash
forge autocomplete bash    # generates completions and prints a source line

Then add the printed line to ~/.bashrc (or ~/.bash_profile on macOS) and reload:

Bash
# Example — the exact path is shown by the command above
echo 'FORGE_AC_BASH_COMPFUNC_PATH=~/Library/Caches/cdx-forge/autocomplete/functions/bash/forge.bash && test -f $FORGE_AC_BASH_COMPFUNC_PATH && source $FORGE_AC_BASH_COMPFUNC_PATH;' >> ~/.bashrc
source ~/.bashrc

Refreshing After Upgrades​

After every CLI upgrade or local rebuild, refresh the autocomplete cache so new commands and flags appear:

Bash
forge autocomplete --refresh-cache
rm -f ~/.zcompdump*    # zsh only
exec zsh               # zsh only — or restart your terminal

On Linux, the cache directory is ~/.cache/cdx-forge/autocomplete instead of ~/Library/Caches/cdx-forge/autocomplete.

Next Steps​

  • Quick Start — Authenticate and preview your first extension