Command Reference

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

Authentication & Setup

Command	Description
forge login	Authenticate with the Developer Console. Prompts for environment (Sandbox or Production). Use -e sandbox|production for non-interactive flows.
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, 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. Prompts to select an environment if not specified with -e — Sandbox or Production.
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.

Diagnostics

Command	Description
forge doctor	Run environment readiness checks (Node, CLI config, auth, git/GitHub, Docker, extensibility monorepo, mobile toolchain).
forge doctor --json	Machine-readable report for scripts and CI.
forge doctor --network	Also probe Developer Console reachability and token exchange (requires login + selected app).
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).

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 --network --strict
forge doctor --check docker.daemon --check git.ghAuth

Environment Variables

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 answers. Requires login.

With no arguments, forge ask starts an interactive docs search session in the terminal: you can type follow-up questions and the CLI streams answers with suggested next prompts. With a question on the command line, forge ask returns a single AI answer and exits (one-shot mode).

Bash

forge ask 'What SDKs does Candescent offer?'
forge ask                                    # interactive mode

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] [--wait]	Submit widget for review with structured metadata.

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 with the OLB playground.
--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
--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)
--no-clear-metro-cache	Skip Metro cache clearing before the Expo sandbox starts — use for faster repeat runs
--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 (validated against creation-time metadata)
--description <text>	Widget description (used in 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
--wait	Poll until the GitHub PR is created

note

By default, forge widget submit runs ESLint, TypeScript type-check, and markdownlint before creating the PR. 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 errors — 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.