Skip to main content

Commandline Interface (CLI)

Pre-release beta

The Forge CLI is currently distributed as a pre-release beta (@cdx-forge/[email protected]). APIs, command flags, and behavior may still change between beta versions. Use of the CLI is governed by the Candescent Developer Agreement (the LICENSE file shipped with each package); third-party open-source attribution is bundled in THIRD_PARTY_LICENSES. Pin to a specific beta version in CI/CD until the GA release is announced.

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.
  • 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, OIDC-authenticated, 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 and OIDC 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​

  • Local previews — forge widget preview and forge aspect preview launch a local OLB Docker playground (web) or an Expo + Metro Bundler sandbox (mobile) for instant feedback against a realistic banking shell.
  • 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.
  • OIDC development — forge oidc up brings up a local mock Identity Provider so you can develop and test auth-aware Aspects and widgets without a real FI environment.
  • Mobile preview — forge widget preview --platform mobile and forge aspect preview --platform mobile open the Expo mobile sandbox for testing on a physical device (Expo Go), iOS Simulator, Android Emulator, or via Expo's tunnel mode.

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 repo pr create, forge repo pr list, and forge repo pr status cover GitHub PR operations directly 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, and --tier stage|prod selects the Production tier (Stage apps vs Prod apps). 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, with additional support for OIDC-based authentication patterns common in partner integrations.

Architecture​

The CLI integrates with several Candescent services and development tools:

ServiceUsed By
Developer Console BFF (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)
Docs Assistant APIask (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
Expo + Metro Bundlerwidget preview --platform mobile, aspect preview --platform mobile (mobile sandbox via Expo Go, simulator, or tunnel)
oidc-sso-toolkit (Docker)oidc commands, aspect preview --template oidc-snippet (local mock IdP)
saml-sso-toolkit (Docker)SAML-based aspect templates and local mock IdP scenarios

Related Packages & Resources​

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

CLI distributions​

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​

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​