@equinor/fusion-framework-cli

Command-line toolkit for developing, building, and publishing Fusion Framework applications and portal templates. Provides a unified developer experience from local development to production deployment.

Features

• Application scaffolding — generate new Fusion apps from predefined templates
• Development server — hot-reload dev server with service discovery and authentication
• Build & bundle — Vite-based production builds with manifest generation
• Publish & tag — upload bundles and configs to the Fusion app/portal service
• Snapshot versions — timestamped preview builds for PRs and CI (--snapshot)
• Portal templates — build, bundle, and deploy portal configurations
• Service discovery — resolve Fusion service endpoints from any environment
• Authentication — Azure AD login, token management, CI/CD token support
• Plugin system — extend the CLI with optional plugin packages

Installation

pnpm add -D @equinor/fusion-framework-cli

The package exposes two binary aliases: fusion-framework-cli and ffc.

Usage

Create a new application

# Interactive template selection
pnpm fusion-framework-cli app create my-app

# Use a specific template
pnpm fusion-framework-cli app create my-app --template react-app

Local development

# Start the dev server (app)
pnpm fusion-framework-cli dev

# Start the dev server (portal)
pnpm fusion-framework-cli portal dev

Build and publish

# Build an application
pnpm fusion-framework-cli app build

# Bundle into a zip archive
pnpm fusion-framework-cli app pack

# Publish bundle + config to an environment
pnpm fusion-framework-cli app publish --env ci --config

# Snapshot build for a PR
pnpm fusion-framework-cli app pack --snapshot pr-123

Authentication

# Interactive login
pnpm fusion-framework-cli auth login

# Retrieve a token
pnpm fusion-framework-cli auth token

# CI/CD: set FUSION_TOKEN environment variable instead

Command overview

Run pnpm fusion-framework-cli <command> --help for detailed options.

API Reference

The package exposes several sub-path exports for programmatic use:

@equinor/fusion-framework-cli (root)

• defineDevServerConfig / defineFusionCli — type-safe config definition helpers
• loadDevServerConfig — load and merge dev-server configuration files
• resolvePackage / resolveEntryPoint — package and entry-point resolution
• RuntimeEnv — runtime environment type used across the CLI

@equinor/fusion-framework-cli/app

• defineAppManifest / defineAppConfig — type-safe manifest and config helpers
• loadAppManifest / loadAppConfig — load and validate app manifest/config files
• createAppManifestFromPackage — generate a manifest from package.json
• mergeAppManifests / mergeAppConfig — deep-merge manifest/config objects
• ApiAppConfigSchema — Zod schema for app config validation

@equinor/fusion-framework-cli/portal

• definePortalManifest / definePortalConfig / definePortalSchema — type-safe helpers
• loadPortalManifest / loadPortalConfig / loadPortalSchema — load and validate files
• createPortalManifestFromPackage — generate a portal manifest from package.json
• validatePortalManifest — validate a manifest against the Zod schema

@equinor/fusion-framework-cli/bin

• buildApplication / buildPortal — programmatic Vite builds
• bundleApp / bundlePortal — build + pack into zip
• uploadApplication / uploadPortalBundle — upload bundles to the service
• tagApplication / tagPortal — tag published versions
• initializeFramework / configureFramework — set up the Fusion Framework for CLI operations
• FusionEnv — enum of supported Fusion environments

@equinor/fusion-framework-cli/utils

• assert / assertFileExists / assertObject — assertion helpers
• fileExists / fileExistsSync — file-existence checks
• writeFile — write files with automatic directory creation
• resolveAnnotations — resolve CI/CD build annotations
• generateSnapshotVersion — create timestamped snapshot versions

Configuration

Application manifest (app.manifest.ts)

import { defineAppManifest } from '@equinor/fusion-framework-cli/app';

export default defineAppManifest((env, { base }) => ({
  ...base,
  // override manifest fields here
}));

Application config (app.config.ts)

import { defineAppConfig } from '@equinor/fusion-framework-cli/app';

export default defineAppConfig((env, { base }) => ({
  environment: { MY_VAR: 'value' },
  endpoints: {
    api: { url: 'https://api.example.com', scopes: ['api://scope/.default'] },
  },
}));

Dev-server config (dev-server.config.ts)

import { defineDevServerConfig } from '@equinor/fusion-framework-cli';

export default defineDevServerConfig((env, { base }) => ({
  ...base,
  // override dev-server options here
}));

Local mock services (mocks/<service>.mock.ts)

Use executable service modules instead of handwritten routes in dev-server.config.ts. Install @equinor/fusion-framework-cli-plugin-mock-server, define each service with defineService, and run ffc mock-server in a separate foreground terminal.

See Develop with mock services for normal discovery overlays, isolated --mock development, and discovery modes.

CLI plugins (fusion-cli.config.ts)

import { defineFusionCli } from '@equinor/fusion-framework-cli';

export default defineFusionCli(() => ({
  plugins: ['@equinor/fusion-framework-cli-plugin-ai'],
}));

Request identification headers

Every request the CLI itself sends to Fusion services identifies the tool and its version, so service operators can tell Fusion Framework traffic apart from other callers when investigating unexpected requests (for example in Fusion Discovery logs).

This covers service discovery lookups and every other client created by configureFramework, publish, upload, check and tag calls, and the AI model, embedding and search index calls. It uses the same X-Fusion-CLI-* convention as the other Fusion CLIs, so one filter on x-fusion-cli-name finds all of them.

Requests forwarded by the dev server (ffc app dev, ffc app serve, ffc portal dev) are not CLI calls. They identify the dev server instead with X-Fusion-Dev-Server-Name and X-Fusion-Dev-Server-Version, plus X-Fusion-Mock: true|false; see the dev server README.

• Diagnostics only. The values can be faked, so never use them for access control. They never contain tokens, secrets, or personal information.
• Caller headers win. A header already set on a request is never overwritten.
• Programmatic use. defaultHeaders is exported from @equinor/fusion-framework-cli/bin, and configureFramework registers it on the framework HTTP client for you.

Documentation

• Developing Apps — build, configure, and deploy applications
• Developing Portals — build and publish portal templates
• Dev Server — architecture and configuration
• Authentication — local and CI/CD authentication setup
• Migration v10 → v11 — breaking changes and upgrade steps