Skip to main content

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 the Candescent developer documentation. Use it as a one-shot question or as an interactive REPL with follow-up suggestions. Requires an active session (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 * and forge env * configure the credentials your code will need at runtime.

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 -e <env> lets you switch between Sandbox and Production. forge env * manages SDK environment variables independently of the login environment.

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:

ServiceUsed By
Developer Console (console.candescent.com / console.sandbox.candescent.com)login, app, aspect submit, submission, collaborator, repo, widget submit
@cdx-forge/di-typescript-sdkapi list, api describe, api call (operation registry + live API calls)
GitHub REST APIrepo pr, submission publish (requires gh auth or GITHUB_TOKEN)
Developer documentation search serviceask (streaming AI search across developer docs)
Nx + cdx-extensibility-appswidget create, widget preview, widget build (local scaffolding and builds)
OLB Docker Playgroundaspect 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 Bundlerwidget preview --platform mobile (iOS Simulator or Android Emulator; Expo Go is a physical-device fallback)

Related Packages & Resources​

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

CLI distributions​

SDKs and code references​

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​

Platform Support​

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

Extension TypeWebMobile
WidgetsNx + Module Federation + OLB playgroundNx + React Native + Expo sandbox
AspectsJavaScript IIFE injected into host pageHTML 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:

Next Steps​