Skip to main content

Installation

warning

The Forge CLI is currently in beta. Behavior and flags may change between beta releases — pin to a specific version in CI/CD until GA.

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:

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​

forge widget preview --platform mobile targets an iOS Simulator or Android Emulator by default (--mobile-device ios|android). You need:

  • iOS Simulator (Xcode on macOS) and/or Android Emulator (Android Studio)
  • For the physical-device fallback only: Expo Go on a phone on the same Wi-Fi as your machine. Use Expo Go's built-in QR scanner, not the iPhone Camera app.

Do not start Expo yourself with npx expo start --tunnel. Re-run forge widget preview. See Mobile preview.

Homebrew (macOS / Linux)​

The recommended installation method for macOS and Linux:

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

Verify the installation:

Bash
forge --version
forge --help
forge doctor

forge doctor runs readiness checks for Node, auth, git/GitHub, Docker, the extensibility monorepo, Nx, and mobile tooling. Use forge doctor --network after forge login (and forge app select for token exchange) to probe BFF reachability and API token exchange. It does not test npm, GitHub, GHCR, or Expo.

To upgrade:

Bash
brew update
brew upgrade forge-cli

To uninstall:

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

npm / pnpm (All Platforms)​

Install globally with pnpm (recommended) or npm:

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

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

Verify the installation:

Bash
forge --version
forge --help
forge doctor

To upgrade:

Bash
pnpm add -g @cdx-forge/cli@beta
# or: npm install -g @cdx-forge/cli@beta

Find the package on the public npm registry: @cdx-forge/cli.

If npm install fails, hangs, or cannot reach registry.npmjs.org (proxy, TLS inspection, or a corporate allowlist), see Troubleshooting and Corporate network and registry access.

Next Steps​

  • Quick Start — Authenticate and preview your first extension
  • Troubleshooting — Doctor, checkout, npm/Nx, Windows, and preview failures