Framework CLI - Application Development
The Fusion Framework CLI empowers you to rapidly build, configure, and deploy modern applications with ease. Whether you’re starting a new project or maintaining an existing app, this CLI streamlines your workflow—from local development to production deployment.
This guide will help you get set up, understand the most important commands, and follow best practices for configuration and CI/CD. Let’s get started building robust, scalable apps with Fusion Framework!
Getting Started
Install the CLI
pnpm add -D @equinor/fusion-framework-cli
# or
npm install --save-dev @equinor/fusion-framework-cli
Scaffold a New App (if supported)
Tip: If you have a template or starter, clone it. Otherwise, create a new directory and initialize your project as below.
mkdir my-fusion-app && cd my-fusion-app
pnpm init
Create Required Files
Minimal package.json
Example
{
"name": "@equinor/fusion-framework-app",
"version": "0.0.0",
"description": "Fusion Framework App",
"main": "dist/index.js",
"files": [
"dist/"
]
}
Build Output Configuration:
The CLI uses themain
field (ormodule
field) in yourpackage.json
to determine where to output the built application bundle. If neither field is specified, it defaults to./dist/bundle.js
.Why this approach? Using the
main
/module
fields ensures your package works correctly when served directly or when developing portals with internal references. This follows Node.js package conventions and enables proper module resolution.Important: The output directory cannot be the project root, the
src
directory, or the current working directory. Always specify a dedicated build directory likedist/
,build/
, or similar.Examples:
"main": "dist/index.js"
→ outputs todist/index.js
"module": "build/app.esm.js"
→ outputs tobuild/app.esm.js
- No
main
/module
specified → defaults todist/bundle.js
Example app.manifest.ts
import { defineAppManifest } from '@equinor/fusion-framework-cli/app';
export default defineAppManifest(async (env, { base }) => ({
...base,
appKey: 'my-app',
displayName: 'My First Awesome Fusion App'
// Add more manifest fields as needed
}));
Example app.config.ts
import { defineAppConfig } from '@equinor/fusion-framework-cli/app';
export default defineAppConfig((env, args) => ({
environment: {
featureFlag: env === 'dev', // Example: enable feature in dev
logLevel: 'info',
customSetting: process.env.CUSTOM_SETTING || 'default-value',
},
endpoints: {
// Define endpoints here if needed, or leave empty
},
}));
Start the Development Server
pnpm fusion-framework-cli dev
Log in to Fusion Framework (if needed)
Note
All HTTP requests to Fusion services require an authorized user.
For example, before running fusion-framework-cli app publish
, make sure you are authenticated using fusion-framework-cli auth login
.
Warning
The fusion-framework-cli auth login
command is only available in interactive environments (such as your local terminal). For CI/CD pipelines or automated deployments, you must provide a valid authentication token using the FUSION_TOKEN
environment variable.
See Authentication for details on setting up tokens for CI/CD.
pnpm fusion-framework-cli auth login
6. Build, Publish, and Upload Config
pnpm fusion-framework-cli publish --env <environment>
pnpm fusion-framework-cli app config --publish --env <environment>
Tip: For CI/CD and automation, set the
FUSION_TOKEN
environment variable. See Authentication for details.
Prerequisites
For Development
- Node.js (LTS recommended)
- pnpm (or npm/yarn)
- A Fusion Framework app template or an existing project
For Deployment
- Your application team must have registered an app in the Fusion Application Service (App Admin)
- A service principal must be set up for deployment and publishing
Troubleshooting & FAQ
- Node.js version error: Ensure you are using a supported Node.js version (LTS recommended).
- Authentication issues: Make sure you are logged in and have the correct permissions for publishing. Use
pnpm fusion-framework-cli auth login
. - Missing manifest/config: Ensure
app.manifest.ts
andapp.config.ts
exist in your project root. - Environment variables: Use
.env
files or your CI/CD system to inject secrets and config values. - Command help: Run any command with
--help
for detailed usage and options. - Still stuck? See Troubleshooting or Authentication.
Configuration
Fusion Framework apps are configured using two main files:
- Application Manifest (
app.manifest.ts
): Defines your app's metadata, capabilities, and integration points. Supports environment-specific variants (e.g.,app.manifest.dev.ts
). - Application Config (
app.config.ts
): Contains runtime configuration, such as environment variables and endpoints. Also supports environment-specific files (e.g.,app.config.dev.ts
).
These files allow you to tailor your app for different environments and deployment scenarios. See the sections below for details and examples.
Application Manifest
Important
The application manifest is bundled with your app during the build process. It should only be generated or referenced as part of the build step in your CI/CD pipeline. The environment-specific variants (e.g., app.manifest.dev.ts
) are for convenience—useful for local development or testing different configurations, but only the manifest present at build time is included in the final bundle.
Tips
If no environment-specific file is found, app.manifest.ts
is used as a fallback.
For environment-specific setup, add files like app.manifest.dev.ts
for development or app.manifest.ci.ts
for CI environments.
Create an app.manifest.ts
file to define your app's manifest. This file describes your app's metadata and configuration:
Important
The function passed to defineAppManifest
should either:
- Return a new manifest object, or
- Return
void
after mutating the providedbase
manifest (which is generated from yourpackage.json
and environment).
Mutating the base
manifest is useful if you want to extend or override values from your package metadata or environment, while returning a new object allows you to fully customize the manifest.
import { defineAppManifest } from '@equinor/fusion-framework-cli/app';
export default defineAppManifest(async (env, { base }) => ({
// You can mutate the base object and return void,
// or return a new manifest object.
}));
Note
The CLI will only include the first matching manifest file based on the environment (e.g., app.manifest.dev.ts
). It will not merge multiple files. If you need to combine settings from different files, you must handle the merging logic yourself within your manifest or config code. You can use the provided mergeAppManifest
utility from the CLI package to help merge manifest objects when needed.
Application Config
Tips
If no environment-specific file is found, app.config.ts
is used as a fallback.
For environment-specific setup, add files like app.config.dev.ts
for development or app.config.ci.ts
for CI environments.
Create an app.config.ts
file to define your app's configuration. This file can export a function or object with your app's runtime configuration:
import { defineAppConfig, mergeAppManifests } from '@equinor/fusion-framework-cli/app';
import createBaseConfig from './app.config';
export default defineAppConfig((env, args) => {
const base = createBaseConfig(env, args);
return mergeAppManifests(base, {
environment: {
someAttr: 'some value',
},
endpoints: {
'my-end-point': {
url: 'https://my-api.com',
scopes: ['https://my-api.com'],
},
},
});
});
Note
The CLI will only include the first matching config file for the environment (e.g., app.config.dev.ts
). It will not merge app.config.ts
and app.config.dev.ts
automatically. If you want to combine base and environment-specific settings, you must implement the merging logic yourself in your configuration code. The CLI provides utilities such as mergeAppManifests
to assist with merging configuration objects.
CI/CD
Continuous Integration and Continuous Deployment (CI/CD) automate the process of building, testing, and deploying your application. By integrating CI/CD pipelines, you ensure that code changes are validated and delivered to your environments efficiently and reliably. This section outlines how to set up CI/CD workflows for Fusion Framework apps.
Best Practice: Build Once, Deploy Many
A recommended approach for CI/CD with Fusion Framework apps is to build your application once and reuse the generated artifact for deployments to multiple environments. This ensures consistency across environments and speeds up your pipeline by avoiding redundant builds.
Workflow Overview:
Build Stage:
Build and bundle your application a single time. Upload the resulting artifact (e.g.,app-bundle.zip
) as a pipeline artifact.Deploy Stage (Matrix):
Use a matrix strategy to deploy the same artifact to multiple environments (such asci
,fqa
,fprd
). For each environment, generate and upload the appropriate configuration using environment-specific variables or secrets.
This pattern minimizes discrepancies between environments and leverages CI/CD efficiency by separating build and deploy concerns.
Example CI/CD Workflow
Below is an example workflow that demonstrates the recommended "build once, deploy many" pattern for Fusion Framework apps. This workflow assumes you are familiar with setting up Node.js and managing pipeline artifacts in your CI/CD system.
jobs:
build:
steps:
- name: Setup node
- name: Bundle application
id: bundle
working-directory: ${{ env.working-directory }}
run: pnpm exec fusion-framework-cli app pack
- name: Upload artifact
deploy:
environment: ${{ matrix.env }} # use deployment environments
strategy:
max-parallel: 1
matrix:
env: ['ci', 'fqa', 'fprd'] # Fusion Environments
steps:
- name: Setup node
- name: Download Artifact
- name: Set Fusion token
- name: Publish application
run: pnpm exec fusion-framework-cli app upload --env ${{ matrix.env }} app-bundle.zip
- step: Upload configuration
run: pnpm exec fusion-framework-cli app config --publish --env ${{ matrix.env }}
Tips
see setting-the-fusion-token-in-github for adding FUSION_TOKEN
to your environment
Example: Using Environment Variables in App Config
You can use environment variables in your app configuration to inject secrets or environment-specific values at build or deploy time. For example, to access values provided by your CI/CD pipeline:
step: Upload configuration
run: pnpm exec fusion-framework-cli app config --publish --env ${{ matrix.env }}
with:
CONFIG_VALUE_FOO: ${{ VAR.ENVIRONMENT_CONFIG_VALUE }}
CONFIG_VALUE_BAR: ${{ SECRETS.ENVIRONMENT_CONFIG_SECRET_VALUE }}
import { defineAppConfig, mergeAppManifests } from '@equinor/fusion-framework-cli/app';
export default defineAppConfig((env, args) => {
return mergeAppManifests(args.base, {
environment: {
foo: process.env.CONFIG_VALUE_FOO,
bar: process.env.CONFIG_VALUE_BAR,
},
});
});
Note
if not app.config.${{ENV}}.ts|js|json
is found it will fallback to app.config.ts|js|json
Commands
Command Overview
The Fusion Framework CLI provides a suite of commands to support the full application lifecycle, from development to deployment. Below is an overview of all available commands with quick links to their detailed usage:
- Dev — Start the development server with hot reloading.
- Publish — Build, upload, and tag your app for deployment.
- Config — Generate or upload your app configuration.
- Build — Build your application and generate deployment artifacts.
- Pack — Bundle your app into a distributable archive.
- Upload — Upload your app bundle to the Fusion app store.
- Tag — Tag a published app version for release management.
- Manifest — Generate your app manifest file.
- Check — Verify your app's registration status.
- Aliases — Deprecated commands and their replacements.
Refer to each section below for detailed options, usage, and examples.
Dev
Start your application in development mode with hot reloading and environment-specific configuration.
Option | Description | Default / Example |
---|---|---|
--debug | Enable debug mode for verbose logging. | false |
--manifest <path> | Path to the app manifest file (app.manifest[.env]?.[ts,js,json] ). | app.manifest.ts |
--config <path> | Path to the app config file (app.config[.env]?.[ts,js,json] ). | app.config.ts |
--env <env> | Runtime environment for the dev server. | local |
--port <port> | Port for the development server. | 3000 |
Usage:
pnpm fusion-framework-cli dev [options]
Examples:
pnpm fusion-framework-cli dev
pnpm fusion-framework-cli dev --port 4000
pnpm fusion-framework-cli dev --manifest ./app.manifest.local.ts --config ./app.config.ts
Tip: Use
--debug
to get detailed logs for troubleshooting during development.
Publish
Publish your application to the Fusion app store (registry) for deployment.
Publish your application to the Fusion app store (registry) for deployment. This command will build (if needed), upload, and tag your app in a single step.
Option/Argument | Description | Default / Example |
---|---|---|
[bundle] | Path to the app bundle to upload. If omitted, the CLI will build and bundle your app automatically. | |
-e , --env | Target environment for deployment (e.g., ci , fqa , fprd ). | |
-m , --manifest | Manifest file to use for bundling (e.g., app.manifest.ts ) (optional). | app.manifest.ts |
-t , --tag | Tag to apply to the published app (latest | preview ). | latest |
-d , --debug | Enable debug mode for verbose logging. | false |
--token | Authentication token for Fusion. | |
--tenantId | Azure tenant ID for authentication. | |
--clientId | Azure client ID for authentication. |
Usage:
pnpm fusion-framework-cli publish [bundle] [options]
Examples:
pnpm fusion-framework-cli publish
pnpm fusion-framework-cli publish --env prod --manifest app.manifest.prod.ts
pnpm fusion-framework-cli publish --tag latest app-bundle.zip
Note
- If you provide a bundle file, it will be uploaded directly. If not, the CLI will build and bundle your app before uploading.
- The
--tag
option lets you mark the published version (e.g., aslatest
orpreview
) for easier deployment targeting. - Authentication options (
--token
,--tenantId
,--clientId
) can be set via CLI flags or environment variables. - If any step fails (build, upload, or tagging), an error will be logged and the process will exit with a non-zero code.
Config
Upload your application configuration to the Fusion app store (registry).
Upload or generate your application configuration for the Fusion app registry.
The config
command allows you to generate your app's configuration and either output it locally (to stdout or a file) or publish it directly to the Fusion app registry for a specific environment.
Option/Argument | Description | Default / Example |
---|---|---|
[config] | Config build file to use (e.g., app.config[.env]?.[ts,js,json] ). | app.config.ts |
-e , --env <env> | Target environment for the configuration. | |
-o , --output | Output to stdout or a file path. Ignored with --publish . | stdout |
--publish | Publish the generated config to the Fusion app registry. | |
--manifest <path> | Path to the app manifest file (required with --publish ). | |
--debug | Enable debug mode for verbose logging. | false |
--silent | Silent mode, suppresses output except errors. | false |
--token | Authentication token for Fusion (only relevant with --publish ). | |
--tenantId | Azure tenant ID for authentication (only relevant with --publish ). | |
--clientId | Azure client ID for authentication (only relevant with --publish ). |
Usage:
pnpm fusion-framework-cli app config [config] [options]
Examples:
# Output config to stdout for the current environment
pnpm fusion-framework-cli app config
# Output config for 'prod' environment to a file
pnpm fusion-framework-cli app config --env prod --output ./dist/app.config.json
# Publish config for 'prod' environment to the registry
pnpm fusion-framework-cli app config --publish --manifest app.manifest.ts --env prod
# Use a custom config file for a specific environment
pnpm fusion-framework-cli app config my-custom.config.ts --env ci
Note
- When using
--publish
, you must specify a manifest file with--manifest
and cannot set--env
todev
. - The
--output
option is ignored when publishing; the config is uploaded directly to the registry. - Authentication options (
--token
,--tenantId
,--clientId
) are only relevant when publishing and can be set via CLI flags or environment variables. - If any step fails, an error will be logged and the process will exit with a non-zero code.
Build
Build your application and generate the necessary artifacts for deployment:
Option/Argument | Description | Default / Example |
---|---|---|
[manifest] | Manifest file to use for building (e.g., app.manifest.ts ). If omitted, searches for a default manifest file. | app.manifest.ts , app.manifest.js , app.manifest.json |
-d , --debug | Enable debug mode for verbose logging. | false |
Usage:
pnpm fusion-framework-cli build [manifest] [options]
Examples:
pnpm fusion-framework-cli build
pnpm fusion-framework-cli build app.manifest.dev.ts --debug
Note
The build output location is determined by the main
field (or module
field) in your package.json
. If neither field is specified, the CLI defaults to ./dist/bundle.js
. This approach ensures your package works correctly when served directly or when developing portals with internal references, following Node.js package conventions for proper module resolution. The output directory cannot be the project root, the src
directory, or the current working directory.
Examples:
"main": "dist/index.js"
→ builds todist/index.js
"module": "build/app.esm.js"
→ builds tobuild/app.esm.js
- No
main
/module
specified → defaults todist/bundle.js
Pack
Build a distributable app bundle archive for deployment.
Option/Argument | Description | Default / Example |
---|---|---|
[manifest] | Manifest file to use for bundling (e.g., app.manifest.ts ). If omitted, searches for a default file. | app.manifest.ts , etc. |
-a , --archive | Name of the output archive file. | app-bundle.zip |
-o , --output | Directory where the archive will be saved. | Current working directory (./ ) |
-d , --debug | Enable debug mode for verbose logging. | false |
Usage:
pnpm fusion-framework-cli pack [manifest] [options]
Examples:
pnpm fusion-framework-cli pack
pnpm fusion-framework-cli pack app.manifest.dev.ts --archive my-app.zip --output ./dist
[!NOTE] The
pack
command will also build your application before bundling. It bundles your application and all necessary files into an archive for deployment. If no manifest is provided, it will search for a defaultapp.manifest.[ts|js|json]
in the current directory.Additionally, the
pack
command generates ametadata.json
file alongside the archive. This file records the app name and version of the build, which can be useful for tracking and deployment automation.
Upload
Upload your Fusion application bundle to the Fusion app store (registry).
Option/Argument | Description | Default / Example |
---|---|---|
[bundle] | Application bundle to upload (e.g., app-bundle.zip ). If omitted, uses the default archive name. | app-bundle.zip |
-k , --appKey | Application key. If not provided, resolved from the manifest file. | |
-e , --env | Target environment for upload (e.g., ci , fqa , fprd ). | |
-d , --debug | Enable debug mode for verbose logging. | false |
--token | Authentication token for Fusion. | |
--tenantId | Azure tenant ID for authentication. | |
--clientId | Azure client ID for authentication. |
Usage:
pnpm fusion-framework-cli app upload [bundle] [options]
Examples:
pnpm fusion-framework-cli app upload
pnpm fusion-framework-cli app upload my-app-bundle.zip --appKey my-app
pnpm fusion-framework-cli app upload --env prod
pnpm fusion-framework-cli app upload --debug
Note
The upload
command uploads a distributable application bundle to the Fusion app registry. You can specify the application key directly or let the command resolve it from the manifest file. Supports environment selection and debug mode. If no bundle is provided, the CLI will use the default archive name (app-bundle.zip
).
If the upload fails, an error will be logged and the process will exit with a non-zero code.
Tag
Tag a published application version in the Fusion app store (registry).
Tag a specific version of your Fusion application in the Fusion app registry for release management.
The tag
command applies a tag (such as latest
, preview
, or stable
) to a published application version. This helps you manage which version is considered the default for deployment or preview purposes.
Argument/Option | Description | Default / Example |
---|---|---|
<tag> | Tag to apply (latest | preview | stable ). | |
-p, --package | Package to tag in format name@version. | |
-m, --manifest <string> | Manifest file to use for resolving app key and version. | app.manifest.ts |
--debug | Enable debug mode for verbose logging. | false |
--silent | Silent mode, suppresses output except errors. | false |
-e, --env <env> | Target environment. | |
--token | Authentication token for Fusion. | |
--tenantId | Azure tenant ID for authentication. | |
--clientId | Azure client ID for authentication. |
Usage:
pnpm fusion-framework-cli app tag <tag> [options]
Examples:
pnpm fusion-framework-cli app tag latest
pnpm fusion-framework-cli app tag preview --env prod --manifest app.manifest.prod.ts
pnpm fusion-framework-cli app tag latest --package my-app@1.2.3
[!TIP] You can roll back a release by tagging a previous build as
latest
. Simply run the tag command with the desired version to make it the active release for deployment.
Note
- The
tag
command requires a published application version. You can specify the package name and version using--package
, or let the CLI resolve them from your manifest file. - Supported tags are:
latest
andpreview
. - Authentication options (
--token
,--tenantId
,--clientId
) can be set via CLI flags or environment variables. - If tagging fails, an error will be logged and the process will exit with a non-zero code.
Manifest
Generate and output your application manifest for Fusion apps.
Option/Argument | Description | Default / Example |
---|---|---|
[manifest] | Manifest build file to use (e.g., app.manifest[.env]?.[ts,js,json] ). | app.manifest.ts |
-d, --debug | Enable debug mode for verbose logging. | false |
-o, --output <path> | Write manifest to the specified file (default: stdout). | stdout |
-s, --silent | Silent mode, suppresses output except errors. | false |
Usage:
pnpm fusion-framework-cli app manifest [manifest] [options]
Examples:
pnpm fusion-framework-cli app manifest
pnpm fusion-framework-cli app manifest app.manifest.prod.ts --output ./dist/app.manifest.json
pnpm fusion-framework-cli app manifest --debug
Tip: By default, the manifest is printed to stdout. Use
--output
to write it to a file for use in CI/CD pipelines or for inspection.
Check
Check if a Fusion application is registered in the Fusion app store (registry).
Checks if your application is registered in the Fusion app store and helps identify registration or configuration issues.
Option/Argument | Description | Default / Example |
---|---|---|
-d , --debug | Enable debug mode for verbose logging. | false |
-e , --env <env> | Specify the environment (see available environments). | |
--token <token> | Provide an authentication token (if required). |
Usage:
pnpm fusion-framework-cli app check [options]
Examples:
pnpm fusion-framework-cli app check
pnpm fusion-framework-cli app check --env prod --debug
Note
- Use this command to verify your app's registration status in the Fusion app store.
- Supports authentication and environment selection.
- Use
--debug
for verbose output to help troubleshoot registration issues.
Aliases (Deprecated Commands)
Important
Deprecated Command Aliases:
The Fusion Framework CLI previously supported several build-*
commands for app lifecycle tasks. These commands are now deprecated in favor of more consistent and future-proof command names (pack
, upload
, manifest
, publish
).
Why the change?
- The new command names are shorter, clearer, and better reflect their purpose.
- This change aligns with industry standards and prepares for future CLI enhancements.
- Deprecated commands will be removed in future versions—update your scripts and workflows now to avoid breaking changes.
For a full migration guide, see Migration v10 to v11.
The CLI will warn you and redirect to the new command when you use a deprecated alias, applying any necessary options automatically. See the table below for mappings:
Deprecated Command | New Command | Notes |
---|---|---|
build-pack | pack | Warns and sets default archive if not specified. |
build-upload | upload | Warns, maps --service to --env , and sets bundle argument if omitted. |
build-manifest | manifest | Warns and redirects to the new command. |
build-publish | publish | Warns, maps --service to --env . |
Note
The --service
option is deprecated and replaced by --env
. Using --service
will result in an error.
Example:
pnpm fusion-framework-cli build-pack
# Outputs a deprecation warning and runs 'pack' with compatible options.
Warning
The deprecated commands will be removed in future versions. Please update your scripts and workflows to use the new command names (pack
, upload
, manifest
, publish
) to ensure compatibility with v11 and beyond.
For a full migration guide, see Migration v10 to v11.
Need more examples?
- See the cookbooks directory in the GitHub repository for real-world app examples.
- For migration help, see Migration v10 to v11.
- For advanced configuration, see Authentication and CI/CD.