Framework CLI - Application Development

9/30/25Less than 1 minute

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 the main field (or module field) in your package.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 like dist/, build/, or similar.
Examples:
"main": "dist/index.js" → outputs to dist/index.js
"module": "build/app.esm.js" → outputs to build/app.esm.js
No main/module specified → defaults to dist/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 and app.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 provided base manifest (which is generated from your package.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 as ci, 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.

This command uploads and tags your app for deployment. If no bundle is provided, it will build your app first before uploading and tagging.

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

Important

Building Behavior: The publish command behaves differently based on whether you provide a bundle:

With bundle: Uploads and tags the provided bundle (no building)
Without bundle: Builds, uploads, and tags your app

Additional Notes:

The --tag option lets you mark the published version (e.g., as latest or preview) 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 to dev.
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 to dist/index.js
"module": "build/app.esm.js" → builds to build/app.esm.js
No main/module specified → defaults to dist/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 default app.manifest.[ts|js|json] in the current directory.
Additionally, the pack command generates a metadata.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 and preview.
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.