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), then for tier (Stage apps or Prod apps) when Production is selected. Use -e sandbox|production and --tier stage|prod for non-interactive flows.
forge logout	Clear stored credentials.
forge status	Show auth status, environment, tier (when authenticated to Production), 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. External CLI users see Sandbox and Production.
2. If Production is selected, prompts for tier — Stage apps or Prod apps — unless --tier stage|prod is passed.
3. Checks if an existing session is still valid (server-side verification).
4. If expired, clears credentials and proceeds with fresh login.
5. Opens the Developer Console in your browser.
6. Imports the session from the browser.
7. Stores session tokens locally (with the selected tier when env is Production).

Production tier — what it controls

The same Production console (console.candescent.com) and BFF login surface manages both Stage-tier and Prod-tier apps. The CLI uses your --tier choice exclusively to decide which DI API base URL forge api call (and any widget/aspect runtime calls) target:

Environment	Tier	DI API base URL
Sandbox	(single tier)	https://api.sandbox.candescent.com/digitalbanking
Production	stage	https://api.candescent.com/digitalbanking/stage
Production	prod	https://api.candescent.com/digitalbanking

When forge login -e production is run non-interactively without --tier, the CLI defaults to --tier stage.

Migrating from previous CLI versions

If your stored session predates the tier model, the CLI clears it on the next command and prints a one-line notice. Re-run forge login to authenticate cleanly. Two cases trigger this:

• A stored environment: stage from before Stage was made internal-only — you'll be asked to log in to Sandbox or Production.
• A stored environment: production without a tier — you'll be asked to log in and pick Stage apps or Prod apps.

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.

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. The authoritative OpenAPI description is documentation/candescent-di-api.yaml in dbk-openapi-devportal (currently 93 operations across 9 x-tagGroups). The @cdx-forge/di-typescript-sdk registry shipped with the CLI is generated from that same spec; 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.

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 9 widget templates (5 web + 4 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 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 (--env production|stage|qal|development).
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, oidc-auth)
--client-id <id>	OIDC client ID (for oidc-auth template)
--fi-domain <domain>	FI domain (for oidc-auth template)

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

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
--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).

OIDC Development

Command	Description
forge oidc up [--pull]	Start the OIDC SSO Toolkit (local mock Identity Provider).
forge oidc down	Stop the toolkit container.
forge oidc status [--reveal]	Health check, credential info, and endpoint URLs.
forge oidc credentials [--json] [--reveal]	Print current auto-generated client credentials.

The OIDC Toolkit auto-generates client_id / client_secret credentials with a 15-minute TTL. On ARM64 hosts (Apple Silicon), the image runs via emulation automatically.

Aspect Commands

Command	Description
forge aspect templates	Browse 15 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 list [--json]	List your Aspect submissions.
forge aspect update	Reminder: new versions are submitted with forge aspect submit (creates a new review).
forge aspect delete [id]	Withdrawals are handled in the Developer Console; the command prints how to check status with forge submission list.

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 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
--client-id <id>	OIDC client ID (for oidc-snippet)
--fi-domain <domain>	FI domain for OIDC auth URL (for oidc-snippet)
--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)
--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 create	Create a PR (auto-detects branch and remote).
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

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