Skip to main content

Quick Start

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.

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

info

If a command fails, run forge doctor and see Troubleshooting.

Step 1: Authenticate with the Developer Console​

Bash
forge login                    # opens Production Developer Console + MFA
forge status                   # shows auth, console environment, org, DI API base

Public npm and Homebrew builds authenticate against the Production Developer Console (https://console.candescent.com). After MFA, if your organization has more than one console environment, the CLI prompts you to choose Sandbox, Staging, or Production — or keeps the default when only one is available.

Switch console environment later without logging out:

Bash
forge env switch               # interactive picker (Sandbox, Staging, Production)
forge env switch sandbox       # or production

Session management is automatic — the CLI keeps your session alive while you're actively running commands and clears expired tokens so forge login re-authenticates cleanly. If your session expires after a period of inactivity, run forge login --force.

important

After forge env switch, app selection is cleared. Run forge app select again before forge api call or submission commands.

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 Developer Console exchanges it for short-lived OAuth tokens on demand. No client secret is stored on your machine.

Alternative: environment-variable credentials

If you can't use the recommended app-based flow (for example, CI without an interactive login 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 (99 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 and runs npm install there. That first install can take several minutes. Subsequent commands reuse this checkout. If clone or install fails, see Troubleshooting.

Preview the widget in the OLB playground:

Bash
forge widget preview my-portfolio                       # web (Nx dev server + OLB Docker)

If you pass --platform mobile on a web-only widget, the CLI auto-switches to web preview and prints Auto-switching to web preview for "…". Create with --platform mobile first for Expo:

Bash
forge widget preview my-portfolio --platform mobile     # iOS Simulator or Android Emulator

Forge opens the simulator or emulator. Physical-device Expo Go is a fallback. See Mobile preview.

Step 6: Search Developer Docs​

Use AI-powered search to find answers across Candescent documentation. This requires an active session — if you have not logged in yet, complete Step 1: Authenticate with the Developer Console above, then confirm with forge status.

Bash
forge ask 'How do I authenticate API requests?'    # one-shot question
forge ask                                            # interactive session with follow-ups
forge ask --new-session                              # fresh docs chat after a stale session

Console and environment​

See Step 1 for login and forge env switch.

EnvironmentTypical use
SandboxDevelopment and testing
StagingPre-production validation
ProductionLive apps and production submissions

Next Steps​