Commandline Interface (CLI)

The Forge CLI is the unifying command-line interface for the Candescent developer experience. It accompanies you through every phase of the developer journey — learn, build, integrate & test, operate, and scale — without leaving the terminal.

note

Forge is Candescent's umbrella brand for the developer experience. The CLI is one of the products under Forge, alongside the developer documentation portal, the Developer Console, and the SDKs. Throughout this guide, "the CLI" refers specifically to the Forge CLI.

What the CLI Does

The CLI is organized around the developer journey:

Learn

• AI-powered docs search — forge ask runs a streaming AI search across Candescent developer documentation. Use one-shot mode, an interactive session with follow-up menus, or --json for scripts. Reuses a stored docs chat session across calls (--session, --new-session). Requires forge login.
• API discovery — forge api list and forge api describe browse the full Candescent Digital Insight API operation registry from the terminal, including parameter details and examples.
• Template browsing — forge widget templates and forge aspect templates show every starter template, grouped by category, with previews of the generated code.

Build

• Widget scaffolding — forge widget create generates a new web (Module Federation) or mobile (React Native) widget via Nx, with optional template overlays for common patterns (data charts, agent chat, promotional).
• Aspect scaffolding — forge aspect preview --template <id> (and optional --preset <id>) generates ready-to-edit Aspect code: classic UI patterns (banner, toast, modal, countdown), session-aware flows, vendor loaders and GTM-style snippets, mobile JSBridge chat shells, and related patterns. Output can be saved under ./aspects/ for local iteration.
• Application & credential management — forge app selects Developer Console apps; forge env switch changes console environment; forge env load / set / show / clear store SDK credential variables.

Integrate & Test

• Environment diagnostics — forge doctor checks Node, auth, git, Docker, and the extensibility monorepo; add --network to probe BFF reachability and token exchange after login (forge app select is required for token exchange).
• API contracts — forge widget api-contract and forge aspect api-contract document mock and production endpoint shapes for data-backed widgets and vendor presets.
• Local previews — forge widget preview and forge aspect preview launch a local OLB Docker playground (web). Widget mobile preview uses the Expo sandbox. Aspect mobile preview saves HTML and opens it in a browser.
• Live API calls — forge api call <tag>.<operation> executes any DI API operation from the terminal so you can validate integrations as you build them.
• Mobile preview — forge widget preview --platform mobile opens the Expo sandbox on an iOS Simulator or Android Emulator by default. Physical-device Expo Go is a fallback. forge aspect preview --platform mobile writes an HTML file and opens it in a browser.

Operate

• Submission workflow — forge widget submit and forge aspect submit open a structured pull request for review, with built-in lint checks (ESLint + TypeScript + markdownlint) and platform validation.
• Submission tracking — forge submission list, forge submission status, and forge submission dashboard give you cross-cutting visibility into every submission and its review state.
• Publish & deploy — forge submission publish merges the approved PR and triggers the CI deploy pipeline. forge submission deploy promotes a published component to production.
• PR management — forge widget submit and forge aspect submit create review PRs; use forge repo pr list and forge repo pr status to inspect them from the terminal.

Scale

• Repository setup — forge repo init provisions your FI repository for extension development.
• Collaborator management — forge collaborator add / list / remove manages who on your team can submit and manage components.
• Multi-environment workflows — forge login signs in to the Production Developer Console (public builds) in your web browser or with a username and password. forge env switch moves between Sandbox, Staging, and Production console environments without re-login. forge env load / set / show / clear manage SDK credential variables separately.

Work with AI assistants

• MCP server. forge mcp install connects Cursor, Claude Code, and other AI assistants to the CLI, so your assistant can sign you in, call DI APIs, and build, preview, and submit widgets and Aspects.

Who Should Use the CLI

The Forge CLI is designed for two audiences:

Financial Institution Developers

FI developers who build custom widgets and Aspects to extend the Candescent Digital Banking platform for their customers. The CLI handles the full lifecycle: scaffold a project, preview it in a local playground, validate it against live APIs, and submit it through the GitHub-based review process.

Marketplace Partners (Fintechs)

Partners building integrations that multiple financial institutions can adopt. The CLI provides the same development workflow as FI developers.

Architecture

The CLI integrates with several Candescent services and development tools:

Service	Used By
Developer Console (console.candescent.com; console environments via forge env switch)	login, env switch, app, aspect submit, submission, collaborator, repo, widget submit
@cdx-forge/di-typescript-sdk	api list, api describe, api call (operation registry + live API calls)
GitHub REST API	repo pr, submission publish (requires gh auth or GITHUB_TOKEN)
Developer documentation search service	ask (streaming AI search across developer docs)
Nx + cdx-extensibility-apps	widget create, widget preview, widget build (local scaffolding and builds)
OLB Docker Playground	aspect preview, widget preview (local banking shell with widget slots and Aspect injection)
cdx-mock-data-apis (port 4010)	Chart-widget templates, forge widget preview for data-driven widgets
cdx-mock-partners (port 4011)	Partner-vendor scenarios, Aspect previews that load remote vendor scripts (including iframe-sso handoff via mock partners)
Expo + Metro Bundler	widget preview --platform mobile (iOS Simulator or Android Emulator; Expo Go is a physical-device fallback)
AI assistants (Cursor, Claude Code, Claude Desktop, Visual Studio Code, Codex)	mcp (MCP server the assistant starts), mcp install, mcp doctor

Related Packages & Resources

Public packages, container images, and source repositories you may use alongside the Forge CLI:

CLI distributions

• npm — @cdx-forge/cli (install with npm i -g @cdx-forge/cli or pnpm add -g @cdx-forge/cli)
• Homebrew tap — candescent-dev/homebrew-forge (install with brew install candescent-dev/forge/forge-cli)

SDKs and code references

• TypeScript Server SDK — @cdx-forge/di-typescript-sdk on npm (used internally by forge api call; you can also depend on it directly from your own server-side code)
• OpenAPI specs — candescent-dev/openapi (canonical OpenAPI documents the SDKs and CLI registry are generated from)

Sample apps and playgrounds

• cdx-extensibility-apps — github.com/candescent-dev/cdx-extensibility-apps — sample web and mobile widgets/Aspects, plus the playground/web and playground/mobile-sandbox workspaces that forge widget preview and forge aspect preview use under the hood. The CLI auto-clones this repo to ~/.forge/cdx-extensibility-apps on first use.

Local mock servers and dev infrastructure

• OLB Docker Playground (web preview shell) — base image: ghcr.io/candescent-dev/olb-playground. The local compose file in cdx-extensibility-apps/playground/web is configured so widget HTTP calls can reach the host on ports 4010 / 4011.
• cdx-mock-data-apis — github.com/candescent-dev/cdx-mock-data-apis — mock REST data server (port 4010). Used by the chart-widget templates (forge widget create --template data-chart) and any widget that calls a localhost:4010/... URL via the SDK.
• cdx-mock-partners — github.com/candescent-dev/cdx-mock-partners — mock partner/vendor server (port 4011). Used by Aspect templates and presets that load remote vendor scripts (for example engagement-script-loader, iframe-sso).

Mobile preview prerequisites

• Expo Go — expo.dev/go (physical-device fallback for widget mobile preview). Aspect mobile preview is HTML in a browser, not Expo.
• Xcode + iOS Simulator — developer.apple.com/xcode (macOS only)
• Android Studio + Android Emulator — developer.android.com/studio

Platform Support

The CLI supports both web and mobile development for widgets and Aspects:

Extension Type	Web	Mobile
Widgets	Nx + Module Federation + OLB playground	Nx + React Native + Expo sandbox
Aspects	JavaScript IIFE injected into host page	HTML document loaded in a WebView

The --platform flag (available on create, preview, and submit commands) ensures you build and submit for the correct target. Platform is recorded at create/preview time and validated at submit time.

Distribution

The CLI ships through two public channels, both updated automatically on every release:

• npm — @cdx-forge/cli for npm/pnpm users (any platform)
• Homebrew — candescent-dev/forge tap providing the forge-cli formula for macOS and Linux

Next Steps

• Installation — Install the CLI via Homebrew or npm/pnpm
• Quick Start — Authenticate, preview your first Aspect, and scaffold a widget in minutes
• Widget Development — Full guide to creating, previewing, and submitting widgets
• Aspect Development — Templates, preview modes, and the submission workflow
• Command Reference — Complete list of all commands and flags
• Forge CLI MCP server: run Forge workflows from Cursor, Claude Code, and other AI assistants
• Troubleshooting — Doctor, checkout, npm/Nx, Windows, and preview failures