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:

  • Node.js >= 18 (download)
  • Git (for widget scaffolding and PR features)
  • Docker (for the OLB Web Playground — 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 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, and mobile tooling. Use forge doctor --network after forge login and forge app select to verify Developer Console reachability.

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.

Next Steps​

  • Quick Start — Authenticate and preview your first extension