Skip to main content

Quick Start

Pre-release beta

The Forge CLI is currently distributed as a pre-release beta. Behavior and flags may change between betas — pin to a specific version in CI/CD until GA.

Go from installing to live-previewing in under five minutes. This guide walks through authentication, app selection, and previewing your first Aspect and widget.

Step 1: Authenticate with the Developer Console​

Bash
forge login                                  # interactive: pick Sandbox or Production
forge login -e sandbox                       # non-interactive: Sandbox
forge login -e production --tier stage       # Production, Stage-apps tier
forge login -e production --tier prod        # Production, Prod-apps tier

forge login shows two environments: Sandbox and Production. Choosing Production triggers a follow-up tier prompt — Stage apps vs Prod apps — because the same Production console (console.candescent.com) hosts both Stage-tier and Prod-tier apps under one login. The tier you pick determines which DI API base URL the CLI calls for forge api call:

  • Production / Stage apps → https://api.candescent.com/digitalbanking/stage
  • Production / Prod apps → https://api.candescent.com/digitalbanking
  • Sandbox (single tier) → https://api.sandbox.candescent.com/digitalbanking

If you run forge login -e production non-interactively without --tier, the CLI defaults to --tier stage (the safer non-prod surface).

Verify your session:

Bash
forge status               # shows auth status, environment, tier, DI API URL, org, repo

Session management is automatic — the CLI keeps your BFF session alive while you're actively running commands (proactive touch every ~10 minutes plus auto-retry on 401/400) and clears expired tokens so forge login re-authenticates without needing --force. If you step away for 30+ minutes and hit a generic 400 Bad Request: Mandatory fields are missing, run forge login --force.

Step 2: Select an App for API Access​

forge api call and runtime SDK calls authenticate as one of your Developer Console apps. After logging in, pick the app whose credentials should be used:

Bash
forge app list             # show your Developer Console apps
forge app select           # pick one interactively (default if multiple)
forge app select my-app    # or by name

Selecting an app is the recommended path — your app's secret stays server-side and the CLI uses the BFF's token-exchange endpoint to mint short-lived OAuth tokens on demand. No client secret is ever stored on your machine.

Alternative: environment-variable credentials

If you can't use the BFF token-exchange flow (CI without an interactive login, an early-access deployment where token-exchange isn't available yet, or one-off scripts), you can fall back to direct client_credentials with stored env vars:

Bash
forge env load /path/to/.env                       # imports CANDESCENT_* keys
forge env set CANDESCENT_CLIENT_ID=<id>            # or set individually
forge env set CANDESCENT_CLIENT_SECRET=<secret>
forge env set CANDESCENT_INSTITUTION_ID=<inst>

forge api call <operation> --use-env               # opt-in per call

Run forge env show to verify (secrets are masked; --reveal unmasks). Never commit .env files to version control. Where both an app and env vars are configured, the default is app-based auth — pass --use-env to override per call.

Step 3: Preview Your First Aspect​

Create and preview an Aspect using a built-in template:

Bash
forge aspect preview --template banner --message 'Summer savings — limited time!'

This generates a JavaScript Aspect, starts the OLB Docker playground, registers the Aspect, and opens the banking shell in your browser. Reload http://localhost:4200 to see the banner.

tip

For multiline messages from bash/zsh, use ANSI-C quoting so \n is interpreted as a newline:

Bash
forge aspect preview --template banner --message $'Drive smarter with auto loans.\nLower rates, flexible terms.'

Plain single quotes ('...\n...') pass a literal backslash-n, not a newline.

To preview without Docker (local mock dashboard):

Bash
forge aspect preview --template banner --message 'Quick preview' --no-playground

Step 4: Browse and Call APIs​

Explore the Candescent Digital Insight API (93 operations across 9 tag groups):

Bash
forge api list                           # all tag groups
forge api list accounts                  # operations in a tag
forge api describe accounts.list         # parameter details
forge api call accounts.list -p hostUserId=HOST01 -p loginId=login01

Step 5: Scaffold Your First Widget​

Browse available widget templates and create a new widget:

Bash
# Browse templates
forge widget templates

# Create a widget (interactive — prompts for name, platform, template)
forge widget create

# Or specify everything upfront
forge widget create my-portfolio --platform web --template data-chart

On first use, the CLI auto-clones the cdx-extensibility-apps template to ~/.forge/cdx-extensibility-apps. Subsequent commands reuse this checkout.

Preview the widget in the OLB playground:

Bash
forge widget preview my-portfolio                       # web (Nx dev server + OLB Docker)
forge widget preview my-portfolio --platform mobile     # mobile (Expo + Metro Bundler)

For mobile preview, scan the QR code with the Expo Go app (your phone must be on the same Wi-Fi network as your dev machine), or press i / a in the terminal to open an iOS Simulator or Android Emulator.

Step 6: Search Developer Docs​

Use AI-powered search to find answers across Candescent documentation:

Bash
forge ask 'How do I authenticate API requests?'    # one-shot question
forge ask                                            # interactive REPL with follow-ups

Environments​

The CLI supports two environments. The environment you select at login determines which Developer Console you authenticate against; for Production, an additional tier decides which DI API base URL the CLI calls.

EnvironmentTierConsole URLDI API base URL
Sandbox(single tier)https://console.sandbox.candescent.comhttps://api.sandbox.candescent.com/digitalbanking
ProductionStage appshttps://console.candescent.comhttps://api.candescent.com/digitalbanking/stage
ProductionProd appshttps://console.candescent.comhttps://api.candescent.com/digitalbanking
note

Start with the sandbox environment for development and testing. For Production, choose Stage apps when working with apps registered in the Stage tier of the Production Developer Console, and Prod apps for apps registered in the Prod tier. The console host and login are the same for both tiers — only the DI API URL differs.

forge status always shows the current environment, tier (when applicable), and resolved DI API base URL.

Configuration Storage​

The CLI stores configuration in two locations:

StorePath (macOS)Contents
Session & app credentials~/Library/Preferences/cdx-forge-nodejs/config.jsonAuth tokens, selected app, SDK env vars
Mock state~/.config/cdx-forge/mock-state.jsonPersisted mock data for local mode

View your config path with forge status.

Next Steps​