Command Reference

Complete reference for all Forge CLI commands, organized by category.

Authentication & Setup

Command	Description
forge login	Authenticate with the Developer Console. Public npm/Homebrew builds use Production (console.candescent.com). After MFA, may prompt for a console environment (Sandbox, Staging, or Production).
forge login --force	Force re-authentication even if the CLI believes you are still logged in. Use when your session is stale or a command fails with an unexpected authentication error.
forge logout	Clear stored credentials.
forge status	Show auth status, console environment, resolved DI API base URL, org, institution ID, repo, session validity, and config path.
forge setup git	Interactive git/GitHub credential setup for dfh-candescent-extensions.

Authentication Flow

1. Public npm/Homebrew builds open the Production Developer Console in your browser (no -e flag); console environment selection happens after MFA (step 6).
2. Checks if an existing session is still valid (server-side verification).
3. If expired, clears credentials and proceeds with fresh login.
4. Opens the Developer Console in your browser.
5. Imports the session from the browser.
6. Stores session tokens locally. After MFA, may prompt for a console environment (Sandbox, Staging, or Production) when your org has more than one; switch later with forge env switch.

Diagnostics

Command	Description
forge doctor	Run environment readiness checks (Node, CLI, auth, git/GitHub, Docker, extensibility monorepo, Nx, mobile toolchain).
forge doctor --verbose	Include versions, resolved paths, and extra data fields (Nx includes raw --version output). Use this when filing a support ticket.
forge doctor --json	Machine-readable report for scripts and CI.
forge doctor --network	Also probe BFF reachability (needs login) and API token exchange (also needs forge app select). Does not test npm, GitHub, GHCR, or Expo.
forge doctor --strict	Treat warnings as failures (exit code 1).
forge doctor --check <id>	Run only named check(s) (repeatable).
forge doctor --skip <id>	Skip named check(s) (repeatable).
forge doctor --timeout <ms>	Per-check timeout in milliseconds (default 8000). Use 60000 on Windows if nx.invocation times out.
forge doctor --no-color	Disable ANSI colors (also honors NO_COLOR).

Check ids include: runtime.node, runtime.cli, auth.environmentAvailable, auth.loggedIn, auth.sessionExpiry, auth.selectedApp, auth.sdkEnv, git.installed, git.gh, git.ghAuth, docker.cli, docker.daemon, docker.compose, docker.composeFile, ext.root, ext.rootValid, nx.invocation, mobile.watchman, mobile.xcode, mobile.iosSimulator, mobile.androidHome, mobile.androidAvds, mobile.adb, network.bff, network.tokenExchange.

Bash

forge doctor
forge doctor --verbose --timeout 60000
forge doctor --network --strict
forge doctor --check docker.daemon --check git.ghAuth

For failed checks, checkout recovery, npm/Nx, and Windows install issues, see Troubleshooting.

Developer Console Environment

Switch which console environment your session targets (Sandbox, Staging, or Production) without logging out. This is separate from SDK environment variables (forge env load / set / show / clear below).

Command	Description
forge env switch	Interactive picker when your org has other console environments available (including Staging).
forge env switch sandbox	Switch to the Sandbox console environment.
forge env switch production	Switch to the Production console environment.
forge env switch --to <environment>	Same targets as the positional argument (sandbox, production). Use forge env switch without arguments to pick Staging.

After a successful switch, app selection is cleared — run forge app select again for API calls. Use --json for scripting; pass an explicit console environment when using --json or in non-interactive shells.

Bash

forge env switch
forge env switch sandbox
forge env switch production --json
forge status    # console environment (CLI label: Workspace: Sandbox / Staging / Production)

If the CLI reports that available console environments are unknown, re-run forge login to refresh your session.

SDK Environment Variables

Store CANDESCENT_* credentials for forge api call --use-env (independent of the Developer Console environment above).

Command	Description
forge env load <file>	Import CANDESCENT_* variables from a .env file.
forge env set KEY=VALUE ...	Set one or more variables.
forge env show [--reveal]	Display stored variables (secrets masked by default).
forge env clear [-y]	Clear all stored variables.

AI Docs Search

Command	Description
forge ask [question]	Search Candescent developer docs and get AI-powered, streaming answers. Requires forge login.

With no arguments, forge ask starts an interactive session: type questions, get streamed answers, pick follow-ups from a menu, or type q to quit. With a question on the command line, returns a single answer and exits (one-shot mode). The CLI reuses a stored docs chat session across calls for conversation continuity.

Flag	Description
--json	Output full response as JSON (content, citations, followUps, sessionId).
--no-follow-ups	Hide suggested follow-up questions (one-shot mode).
--no-sources	Hide source citations (one-shot mode).
--session <id>	Reuse a specific docs chat session ID.
--new-session	Start a fresh docs chat (ignore stored session).

Bash

forge ask 'What SDKs does Candescent offer?'
forge ask                                    # interactive mode
forge ask 'How do I submit a widget?' --json
forge ask --new-session                      # after a stale or expired docs session

If forge ask fails with an authentication error, run forge login --force. If it reports an invalid or expired docs chat session, run forge ask --new-session.

App Management

Command	Description
forge app list	List your registered applications.
forge app keys [name]	Show API keys for an application (--reveal to unmask secrets).
forge app select [name]	Select an app for API access (stores client credentials).

API Access

The CLI exposes the Candescent Digital Insight API operation registry in a three-level hierarchy: tag groups → tags → operations (currently 99 operations across 9 tag groups). The registry is generated from the canonical Candescent OpenAPI specifications; run forge api list to confirm counts at runtime after upgrades.

Command	Description
forge api list	List all tag groups, their tags, and operation counts.
forge api list <tag-group>	Drill into a tag group (e.g., core-banking).
forge api list <tag>	List operations in a specific tag (e.g., accounts).
forge api list --search <query>	Search operations by name, description, tag, or tag group.
forge api describe <tag>.<operation>	Show HTTP method, path, SDK accessor, parameters, and examples.
forge api call <tag>.<operation> [-p key=value]	Execute an API operation.
forge api call <tag>.<operation> --use-env	Use CANDESCENT_CLIENT_ID / CANDESCENT_CLIENT_SECRET or CANDESCENT_BEARER_TOKEN from the environment instead of the selected app's server-side token exchange.

By default, forge api call uses credentials from forge app select. Use --use-env when you have SDK env vars loaded via forge env load or forge env set.

Tag Groups

Tag Group	Tags
Authentication	oauth-v1, oauth-v2
Customer Management	registration-and-access, profile-and-status, contact-info
Core Banking	accounts, transactions, banking-activities, images
Business Banking	registration, profile, entitlements
Money Movement	recipients, transfers
Alerts And Notifications	system-alerts, institution-alerts, templates, institution-preferences, user-preferences, notification-channels, history-and-events
Documents And Preferences	institution-disclosures, user-disclosures, electronic-statements
Customer Campaigns	experience-groups, jobs, promotions-suite, audience
MX	users, data, widgets

Widget Commands

Command	Description
forge widget templates [--id <id>] [--platform]	Browse seven widget templates (four web + three mobile) grouped by category.
forge widget create [name] [--platform web|mobile] [--template <id>]	Scaffold a new widget. Prompts for platform and template if omitted.
forge widget list	List widgets in the current project.
forge widget set-urls [name]	Configure production submission URLs in .forge-manifest.json before submit.
forge widget api-contract [template-id]	Show which URLs and JSON responses your backend must return for data-backed widgets (includes curl examples).
forge widget preview [name] [--platform web|mobile] [--port] [--no-playground]	Web: Nx dev server + OLB Docker playground. Mobile: Expo sandbox.
forge widget build <name> [--env]	Production build. Default: production.
forge widget submit [name] [--env] [--force]	Submit widget for review. Name is auto-detected if omitted.

Widget Create Flags

Flag	Description
--platform <web|mobile>	Target platform (prompted if omitted)
--template <id>	Template to use (sdk-demo, data-chart, agent-chat, promotional-card)
--local	Scaffold as plain local files only, no Nx project. Cannot be previewed or submitted.
--dir <path>	Output directory when using --local (default: ./widgets)

Widget API contract

Templates that call a backend during development expose contracts via forge widget api-contract:

Bash

forge widget api-contract                          # interactive picker
forge widget api-contract data-chart
forge widget api-contract data-chart --dataset credit-score
forge widget api-contract agent-chat
forge widget api-contract data-chart --format openapi --copy
forge widget api-contract data-chart --format openapi --write ./chart-api.yaml

Flag	Description
--dataset <id>	With the data-chart template, selects which chart dataset endpoint contract to display. One of: investment-portfolio, spending, credit-score, loan-breakdown, savings-goals, net-worth, income-expense
--format openapi|openapi-json	Emit OpenAPI instead of human-readable output
--copy	Copy OpenAPI output to the clipboard
--write <path>	Write OpenAPI spec to a file

Widget Preview Flags

Flag	Description
--platform <web|mobile>	Target platform (default: web)
--port <n>	Dev server port (default 4200). With the playground on, 4200 is remapped to 4300, then the CLI scans upward for a free port so the OLB shell can keep 4200.
--no-playground	Run Nx dev server only, without Docker
--slot <alias>	Pre-select the playground slot to fill (e.g. widget1). Skips the interactive prompt.
--mobile-device <ios|android>	Mobile preview device: iOS Simulator or Android Emulator (prompted if omitted)
--ready-timeout <seconds>	Seconds to wait for remoteEntry.js before giving up on auto-open (default: 300)
--no-wait-ready	Skip waiting for remoteEntry.js before mount and browser open
--no-mount-api	Skip POST /playground/api/mountRemoteApps on BFF port 3001
--no-clear-metro-cache	Skip deleting Metro cache directories before Expo starts. Expo still launches with --clear.
--no-open	Start the playground without opening the browser
--pull	Pull fresh Docker images before starting the playground

Widget Submit Flags

Flag	Description
--platform <web|mobile|both>	Target platform. both is accepted, then treated as web.
--description <text>	Printed in the local submission summary. Not copied into the PR body.
--env <env>	Submission environment override (default: derived from login env)
--source-url <url>	Target-environment API URL — replaces localhost URLs without prompting
-u, --update	Push to the existing open PR for this widget instead of opening a new one
--new	Always create a new PR even if one is already open
--retry-pr	Open a PR for a branch that was pushed on a prior submit when PR creation failed (requires recorded pendingBranch metadata)
--no-lint	Skip the pre-submit ESLint, TypeScript, and markdownlint checks
--force	Skip platform and metadata validation
-v, --verbose	Show GitHub PR diagnostics (branch visibility, base branch, API errors)

note

By default, forge widget submit runs Nx ESLint, npm run typecheck, and markdownlint before creating the PR. Markdownlint warnings do not abort the submit. TypeScript failures do. ESLint rule failures abort; a missing ESLint plugin or missing @nx/eslint is a skip or warning, not a failure. Use --no-lint for debugging if you need to bypass these checks. Common lint fixes:

• no-console: replace console.log with proper logging or remove debug statements.
• Markdown warnings: ensure README.md has no trailing spaces, uses consistent heading levels, and has a blank line before/after fenced code blocks.

Playground (OLB Web)

Command	Description
forge playground up [--pull] [--no-open]	Start the local OLB Docker playground.
forge playground restart	docker compose down && up -d (fresh shell state).

Visit Web Playground for setup, Aspect Manager, and troubleshooting beyond forge playground up.

Aspect Commands

Command	Description
forge aspect templates	Browse 14 Aspect templates and presets (mock-partner shortcuts). Supports filters, code preview, and machine-readable output.
forge aspect create [...]	Same flags as forge aspect preview. Scaffolds and previews an Aspect only; does not open a submission PR.
forge aspect preview [...]	Preview in the OLB playground (default), local mock dashboard, or mobile HTML.
forge aspect submit <name> [...]	Submit an Aspect for review (opens a PR on your extensions repository).
forge aspect api-contract [--preset <id>]	Show the API contract your backend must implement for a preset (vendor URLs + FI-hosted endpoints).
forge aspect list [--json]	List your Aspect submissions.
forge aspect update	Reminder: new versions are submitted with forge aspect submit (creates a new review).

Aspect templates flags

Flag	Description
--id <id>	Show details for one template id
--platform <web|mobile|both>	Filter templates by platform
--context-aware	Show only context-aware templates
--preview-code	Print generated JavaScript for the template
--preset <id>	With --id and --preview-code, apply a preset (mock URLs and options). Incompatible presets are rejected.
--message <text>	Message passed into --preview-code generation
--format ids	One template id per line (for scripts and shell completion). Respects --platform / --context-aware.
--format preset-ids	One preset id per line

Aspect API contract

Presets that rely on mock partners or FI-hosted handoff endpoints document their contracts via forge aspect api-contract:

Bash

forge aspect api-contract
forge aspect api-contract --preset engagement-script-loader
forge aspect api-contract --preset script-config-retail --format openapi --copy
forge aspect api-contract --template vendor-script-loader   # list compatible presets
forge aspect api-contract --preset iframe-sso --format openapi --write ./iframe-sso.yaml

Flag	Description
--preset <id>	Preset id (see forge aspect templates --format preset-ids)
--template <id>	Filter to presets compatible with a template
--format openapi|openapi-json	Emit OpenAPI instead of human-readable output
--copy	Copy OpenAPI output to the clipboard
--write <path>	Write OpenAPI spec to a file

Aspect Preview Flags

Flag	Description
--platform <web|mobile>	Target platform (default: web)
--playground / --no-playground	Register the Aspect in the OLB Docker playground (default), or use the built-in mock banking dashboard without Docker
--open / --no-open	After registering in the playground, open the OLB shell in the browser (default: open)
--pull	Pull fresh Docker images before starting the playground
--template <id>	Use a built-in Aspect template
--preset <id>	Apply a preset bundle of mock partner URLs and options (requires --template)
--message <text>	Message for the template (use $'...' in bash/zsh for real newlines)
--cta-text / --cta-url	CTA label and URL when the template supports them
--code-file <path>	Preview a JavaScript file with live reload (--no-playground)
--code <snippet>	Preview an inline JavaScript snippet
--save <path>	Custom save path for generated code
--no-save	Do not save generated code to disk
--port <n>	Mock preview server port for --no-playground only (default: 3456). Does not change mock partner URLs.
MOCK_PARTNERS_URL / MOCK_PARTNERS_PORT	Optional environment variables so the CLI can discover a mock partner server; otherwise it auto-detects common local ports.

Aspect Submit Flags

Flag	Description
--template <id>	Use a built-in template
--message <text>	Message text for the template (use $'...' for newlines)
--cta-text <text>	CTA button text for the template (requires --template)
--cta-url <url>	CTA button URL for the template (requires --template)
--code-file <path>	Submit from a JavaScript file
--code <snippet>	Submit an inline JavaScript snippet (alternative to --code-file)
--description <text>	Aspect description (used in the PR body)
--platform <web|mobile|both>	Target platform (validated against creation-time metadata)
--load-with-url <url>	Mobile aspect load URL — the production URL the OLB mobile shell will load the Aspect from (required for --platform mobile)
--iframe / --no-iframe	Render the Aspect in an iframe (default: --iframe)
--pr <number>	Update an existing PR instead of creating a new one
--env <env>	Submission environment override (default: derived from login env)
--force	Skip platform and metadata validation
--wait	Wait for the GitHub PR to be created before exiting
--save / --no-save	Save generated code to ./aspects/<name>.js (default: --save)

Submission Tracking

Command	Description
forge submission list [--status] [--json]	List submissions with status, PR number, and date.
forge submission status <id>	Detailed status with review timeline.
forge submission dashboard [--json]	Aggregated stats and recent activity.
forge submission publish [name] [-y] [--method]	Publish an approved submission — merges the PR (default: squash) and triggers the CI build/deploy. Picker if name is omitted.
forge submission deploy [name] [-y]	Deploy a published component to production via the Experience Group. Picker if name is omitted.

Submission Publish Flags

Flag	Description
-y, --yes	Skip confirmation
--method <squash|merge|rebase>	Merge method (default: squash)

Lifecycle: Submit → PR Created → In Review → Approved → Publish (merge PR + CI deploy) → Deploy (production)

Collaborator Management

Command	Description
forge collaborator add <email>	Add a collaborator (triggers GitHub invitation).
forge collaborator list	List collaborators who can manage submissions.
forge collaborator remove <email> [-y]	Remove a collaborator.

Repository & Pull Requests

Command	Description
forge repo init [--collaborator email]	Create your FI repository under dfh-candescent-extensions.
forge repo status [--org name]	Check repository and organization status.
forge repo pr list --repo <name>	List PRs (--state open|closed|all).
forge repo pr status <number> --repo <name>	PR details including checks, labels, and reviews.

note

Submission PRs are created by forge widget submit and forge aspect submit, not by a separate repo pr create command.

PR commands require GitHub authentication. Install GitHub CLI (brew install gh) and run gh auth login, or set the GITHUB_TOKEN environment variable.