@equinor/fusion-framework-cli 11.0.0-next.0 → 11.0.0-next.3

package/docs/auth.md

@@ -0,0 +1,190 @@
+---
+title: Fusion Framework CLI - Authorization
+description: >
+  Comprehensive guide to authentication and authorization in the Fusion Framework CLI, covering Azure AD, MSAL, local development, CI/CD, service principals, and best practices for secure automation and integration.
+category: cli
+related:
+  - '@equinor/fusion-framework-module-msal-node/README.md'
+tags:
+  - cli
+  - fusion-framework
+  - msal
+  - azure
+  - azure-ad
+  - authentication
+  - authorization
+  - service-principal
+  - github-actions
+  - ci
+  - cd
+  - devops
+  - security
+keywords:
+  - azure ad
+  - msal
+  - access token
+  - authentication flow
+  - interactive login
+  - silent authentication
+  - token caching
+  - secure storage
+  - app registration
+  - tenant id
+  - client id
+  - scopes
+  - api permissions
+  - oidc
+  - sso
+  - cloud identity
+  - developer experience
+---
+
+# Authentication with Fusion Framework CLI
+
+The Fusion Framework CLI provides secure, robust authentication for both automation and interactive development scenarios by leveraging Microsoft's MSAL (Microsoft Authentication Library) and Azure Active Directory (Azure AD). Authentication is handled through the Fusion Framework for Node.js, using the `@equinor/fusion-framework-module-msal-node` package, which is built on top of Microsoft's official `msal-node` library. This ensures standards-compliant, up-to-date authentication flows and seamless integration across Fusion Framework applications and tools.
+
+Key features include:
+- **Multiple authentication modes:**
+  - `token_only`: Use a pre-provided token (e.g., for CI/CD and automation).
+  - `silent`: Acquire tokens silently using cached or refresh tokens (background services, scripts).
+  - `interactive`: Prompt for authentication via a local HTTP server (CLI tools, development).
+- **Secure token storage:** Tokens are encrypted at rest using platform-specific mechanisms (e.g., Secure Enclave on macOS, DPAPI on Windows).
+- **Consistent experience:** The same authentication logic and token handling is used across CLI and app environments.
+
+## Azure AD Concepts: Tenant, Client App, and Scopes
+
+When configuring authentication for the Fusion Framework CLI, you will encounter several Azure Active Directory (Azure AD) concepts:
+
+### Tenant
+- The **tenant** is your organization's Azure AD directory. It is identified by a unique tenant ID (a GUID) or a domain name (e.g., `contoso.onmicrosoft.com`).
+- The tenant controls user identities, app registrations, and access policies.
+- **For most use cases, you do not need to specify the tenant—by default, the CLI uses the Equinor tenant.**
+
+### Client App (Application Registration)
+- The **client app** refers to an application registered in your Azure AD tenant. This registration provides a unique **client ID** used to identify your app when requesting tokens.
+- **The Fusion Framework CLI uses the default Fusion CLI app registration for authentication, so you do not need to provide a client ID.**
+- The client app registration defines what permissions (scopes) your app can request and how it can authenticate (e.g., client credentials, interactive login).
+
+### Scopes
+- **Scopes** define the permissions your app is requesting when acquiring an access token. Scopes are typically in the form of URLs (e.g., `https://my-service.com/.default` or a custom API scope).
+- The scopes you request must be granted to your client app registration in Azure AD.
+- When using the CLI or configuring CI/CD, you should provide the scopes required for your target environment or API.
+
+> [!TIP]
+> For most development and deployment scenarios, the CLI provides sensible defaults for tenant and client app. You only need to specify the scopes required for your specific target environment or API.
+
+## Local Development
+
+### Logging in with the CLI
+
+For local development, you should authenticate interactively using the CLI's built-in login command. This uses the `interactive` authentication mode, which will prompt you to sign in via your browser and securely store your credentials for future CLI commands.
+
+To log in, run:
+
+```sh
+fusion-framework-cli auth login
+```
+
+- This will open a browser window for you to complete the Azure AD sign-in process.
+- After successful login, your credentials are securely cached using platform-specific secure storage (e.g., Secure Enclave on macOS, DPAPI on Windows).
+- You only need to log in once per session or until your token expires.
+
+If you ever need to clear your cached credentials, you can run:
+
+```sh
+fusion-framework-cli auth logout
+```
+
+This will remove your stored tokens and require you to log in again for future CLI operations.
+
+### Authentication Options in Development
+
+The CLI provides several authentication-related options for advanced scenarios or custom environments:
+
+- **--tenantId**: The Azure Active Directory tenant ID. You can override the default using this option or the `FUSION_TENANT_ID` environment variable. For most users, this is not required.
+- **--clientId**: The client ID of the application registered in Azure AD. You can override the default using this option or the `FUSION_CLIENT_ID` environment variable. For most users, this is not required.
+- **--token**: The Azure AD access token. If provided (or set via `FUSION_TOKEN`), tenant and client options are ignored for that command. This is useful for advanced automation or CI/CD scenarios.
+- **--scope**: One or more Azure audience scopes, usually the application ID URI of the API you want to access, followed by `.default`. You can override the default using this option or the `FUSION_AUTH_SCOPE` environment variable. This is the most common option to change for custom API access.
+
+**How these options work:**
+- If you provide a token, tenant and client options are ignored for that command.
+- Tenant and client IDs must be valid UUIDs if specified.
+- Scopes must be non-empty strings.
+
+These options allow you to use the CLI with custom tenants, client apps, or tokens if needed, but for most development scenarios, the built-in defaults are sufficient and only the `--scope` option is commonly changed. This flexibility supports both simple and advanced authentication needs, making it easy to get started while enabling custom setups for more complex environments.
+
+## CI/CD
+
+### Setting the Fusion Token in GitHub
+
+To publish or deploy your Fusion Framework app, you need to authenticate and set the `FUSION_TOKEN` environment variable. This token is required for secure access to Fusion APIs during CI/CD workflows.
+
+You can obtain and set the `FUSION_TOKEN` using the Azure CLI as part of your pipeline steps. For example:
+
+This ensures the `FUSION_TOKEN` is available as an environment variable for subsequent steps, such as publishing source code or config.
+
+```yml
+# This GitHub Action authenticates with Azure and retrieves an access token for use as FUSION_TOKEN.
+#
+# - The Azure Login step uses the azure/login action to authenticate with Azure using the provided client and tenant IDs.
+# - The Get Access Token step runs the Azure CLI to acquire an access token for the specified scope, then sets it as the FUSION_TOKEN environment variable for subsequent steps.
+#
+# This makes the token available for publishing, deploying, or running Fusion CLI commands that require authentication.
+#
+# Example usage in a workflow:
+#
+# steps:
+#   - name: Acquire Fusion Token
+#     uses: ./.github/actions/fusion-token
+#   - name: Fusion CLI command
+#     run: fusion-framework-cli app check
+#
+# ---
+# How to set up a Service Principal in Azure for CI/CD:
+#
+# 1. Sign in to Azure CLI:
+#      az login
+# 2. Create a new service principal (replace <NAME> and <SCOPE> as needed):
+#      az ad sp create-for-rbac --name <NAME> --role contributor --scopes <SCOPE>
+#    - This will output appId (client-id), password (client-secret), and tenant.
+# 3. Grant the service principal API permissions if needed (e.g., to call Fusion APIs):
+#    - In Azure Portal, go to Azure Active Directory > App registrations > [Your App] > API permissions.
+#    - Add the required API permissions and grant admin consent.
+# 4. Store the client-id, client-secret, and tenant-id as GitHub Action secrets.
+# 5. Use these secrets in your workflow as shown below.
+# 6. (Optional) For more on setting up environment variables in GitHub Actions workflows, see:
+#    https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment
+#
+# For more details, see:
+# https://learn.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal
+# https://learn.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli
+#
+name: Azure Login and Get Access Token
+description: Authenticates with Azure and retrieves an access token
+inputs:
+  client-id:
+    description: >
+      The Azure AD Application (client) ID to use for authentication. This should correspond to an app registration with permissions to request the required scopes.
+    required: true
+  tenant-id:
+    description: >
+      The Azure AD Tenant ID (directory) to authenticate against. This identifies the Azure AD instance where the app is registered.
+    required: true
+  scope:
+    description: >
+      The scope(s) for the access token, typically the Application ID URI of the API you want to access, followed by /.default (e.g., https://my-api/.default). Multiple scopes can be space-separated.
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Azure Login
+      uses: azure/login@v2
+      with:
+        client-id: ${{ inputs.client-id }}
+        tenant-id: ${{ inputs.tenant-id }}
+        allow-no-subscriptions: true
+    - name: Get Access Token
+      shell: bash
+      run: |
+        echo "FUSION_TOKEN=$(az account get-access-token --scope ${{ inputs.scope }} --query accessToken --output tsv)" >> $GITHUB_ENV
+```

package/docs/libsecret.md

@@ -0,0 +1,97 @@
+---
+title: Enabling Secure Credential Storage with libsecret
+description: Instructions for installing libsecret on Linux to enable secure credential storage for your CLI.
+tags: 
+  - cli
+  - authentication
+  - keytar
+  - libsecret
+  - linux
+  - security
+  - credentials
+  - msal
+  - nodejs
+  - keychain
+keywords:
+  - secure credential storage
+  - keychain
+  - linux
+  - node.js
+  - password manager
+  - system keyring
+  - msal-node
+  - credential storage
+  - cross-platform
+  - token caching
+  - npm
+  - secrets
+  - cli authentication
+  - keytar troubleshooting
+---
+
+This CLI enables secure authentication and persistent token caching by storing credentials in your system's keychain. It uses [`@azure/msal-node`](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node) for authentication, which relies on the [`keytar`](https://github.com/atom/node-keytar) module for secure credential storage.
+
+> **What is `libsecret`?**  
+> [`libsecret`](https://wiki.gnome.org/Projects/Libsecret) is a library for storing and retrieving passwords and secrets. On Linux, `keytar` depends on `libsecret` to access the system keyring.
+
+## Platform Requirements
+
+- **Windows:** No additional dependencies. `keytar` uses the Windows Credential Manager.
+- **macOS:** No additional dependencies. `keytar` uses the macOS Keychain. If you encounter unusual issues (rare), you can optionally try installing `libsecret`:
+  ```bash
+  brew install libsecret
+  ```
+- **Linux:** You must install `libsecret` for secure credential storage. See below for instructions.
+
+## Linux Installation
+Install the `libsecret` library based on your distribution:
+
+- **Ubuntu/Debian**:
+  ```bash
+  sudo apt-get update
+  sudo apt-get install -y libsecret-1-0 libsecret-1-dev
+  ```
+  > Both runtime and development packages are required for building native modules.
+- **Fedora**:
+  ```bash
+  sudo dnf install -y libsecret libsecret-devel
+  ```
+  > Install both runtime and development packages if you plan to build native modules.
+- **Arch Linux**:
+  ```bash
+  sudo pacman -S --noconfirm libsecret
+  ```
+
+## Verifying Installation
+After installing `libsecret`, rebuild `keytar` to ensure it links correctly:
+
+```bash
+npm rebuild keytar
+```
+
+You can verify that `keytar` is working by running your CLI and checking for credential storage warnings. Alternatively, you can test with a simple script:
+
+```js
+const keytar = require('keytar');
+keytar.setPassword('test-service', 'test-account', 'test-password')
+  .then(() => keytar.getPassword('test-service', 'test-account'))
+  .then(console.log)
+  .catch(console.error);
+```
+If you see errors related to `keytar` or `libsecret`, see troubleshooting below.
+
+## Troubleshooting
+- **Missing `libsecret` errors:** Ensure you have installed both the runtime and development packages (e.g., `libsecret-1-0` and `libsecret-1-dev` on Ubuntu/Debian).
+- **Rebuild keytar:**
+  ```bash
+  npm rebuild keytar
+  ```
+- **Still having issues?**
+  - Ensure your system keyring (e.g., GNOME Keyring or KWallet) is running and unlocked. On some headless or minimal Linux environments, you may need to start or configure the keyring daemon manually.
+  - See the [`keytar` troubleshooting guide](https://github.com/atom/node-keytar#troubleshooting).
+  - Consult your distribution's documentation for keyring setup.
+
+## Resources
+- [`keytar` documentation](https://github.com/atom/node-keytar)
+- [`libsecret` project page](https://wiki.gnome.org/Projects/Libsecret)
+- [@azure/msal-node](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node)

package/docs/migration-v10-to-v11.md

@@ -0,0 +1,74 @@
+---
+title: Migration Guide: v10 to v11 CLI Command Changes
+description: >
+  Comprehensive guide to migrating CLI commands from v10 to v11 of the Fusion Framework, including deprecated commands, new command names, authentication changes, and best practices for updating scripts and pipelines.
+category: cli
+related:
+  - ./auth.md
+  - ./application.md
+tags:
+  - cli
+  - fusion-framework
+  - migration
+  - breaking-changes
+  - upgrade
+keywords:
+  - fusion framework
+  - cli commands
+  - v10 to v11 migration
+  - deprecated commands
+  - authentication changes
+  - service discovery
+  - environment configuration
+  - upgrade guide
+  - best practices
+---
+
+# Migration Guide: v10 to v11 CLI Command Changes
+
+With v11, we switched to using the Fusion Framework itself for CLI operations. This change was made to reduce maintenance and improve consistency by reusing the same framework modules (such as service-discovery, authentication, and HTTP) in both Node.js and browser environments. By leveraging the Fusion Framework directly, CLI features and integrations stay up-to-date and benefit from shared improvements across the ecosystem.
+
+## Why This Matters
+- **Unified experience:** The CLI now behaves more like Fusion apps, making it easier to reason about configuration, authentication, and service discovery.
+- **Reduced duplication:** By reusing core modules, bug fixes and new features are shared between CLI and Framework code.
+- **Performance:** The framework is now initialized only when needed (e.g., for HTTP calls or authentication), improving startup time and resource usage.
+
+## Deprecated App Command Aliases
+
+This guide covers command changes for the `fusion-framework-cli app` scope.
+
+The following table lists the old commands and their new equivalents:
+
+| Old Command    | New Command |
+| -------------- | ----------- |
+| build-pack     | pack        |
+| build-upload   | upload      |
+| build-manifest | manifest    |
+| build-publish  | publish     |
+
+When using a deprecated command, the CLI will display a warning message and guide you to use the new command. Deprecated options such as `--service` are no longer supported; use `--env` instead.
+
+> [!WARNING]
+> The deprecated commands will continue to work for now, but they are scheduled for removal in the next major release. Please migrate to the new commands as soon as possible.
+
+### Additional Notes
+- The deprecated `--service` option is no longer supported. Use `--env` for environment selection.
+- Only the new command names will be supported in future versions. Update your CI/CD pipelines and documentation as soon as possible.
+- The deprecated commands are maintained for backward compatibility during the transition to v11, but will be removed in the next major release. Please migrate to the new commands as soon as possible.
+
+## Authentication Changes
+- The `FUSION_TOKEN` environment variable should only be used for CI/CD and automated deployments.
+- For local development, users should authenticate interactively by running:
+  ```sh
+  fusion-framework-cli auth login
+  ```
+  before executing any commands.
+
+## What to Check When Migrating
+- Update all scripts, documentation, and CI/CD pipelines to use the new command names.
+- Remove any usage of the deprecated `--service` option and replace it with `--env`.
+- Ensure your local development workflow uses `fusion-framework-cli auth login` for authentication.
+- Review any custom integrations that may rely on CLI startup behavior, as initialization is now on-demand.
+
+For more details, see the CLI release notes or run `pnpm fusion-framework-cli app --help`.
+

package/docs/portal.md

@@ -0,0 +1,278 @@
+---
+title: Developing Portals with Fusion Framework CLI
+description: >
+  Guide to building, configuring, and deploying portal templates using the Fusion Framework CLI. Includes setup, essential commands, configuration, troubleshooting, and best practices for portal development.
+category: cli
+related:
+  - ./auth.md
+tags:
+  - portal-development
+  - configuration
+  - deployment
+  - commands
+  - troubleshooting
+  - best-practices
+keywords:
+  - fusion-framework-cli portal
+  - fusion portal dev
+  - fusion portal build
+  - fusion portal pack
+  - fusion portal upload
+  - fusion portal tag
+  - fusion portal manifest
+---
+
+# Fusion Framework CLI: Portal Template Development Guide
+
+> **Table of Contents**
+> - [Getting Started](#getting-started)
+> - [Portal Manifest](#portal-manifest)
+> - [Commands](#commands)
+> - [Troubleshooting & FAQ](#troubleshooting--faq)
+
+---
+
+The Fusion Framework CLI enables you to build, configure, and deploy **portal templates** for the Fusion ecosystem. These commands are specifically for creating, building, and managing portal templates—not for managing actual portals.
+
+> **What is a Portal Template?**
+>
+> A portal template is a reusable, versioned package that defines the structure, configuration, and capabilities of a portal. You use the CLI to develop and publish these templates.
+>
+> **The actual portal** is created when you register a portal in the Portal Admin app and configure it according to the schema defined in your template. Portal registration and configuration are managed outside the CLI, in the Fusion Portal Admin UI.
+
+This guide covers the essential commands and best practices for developing and managing portal templates. For information on registering and configuring portals, see the Portal Admin documentation.
+
+## Getting Started
+
+### 1. Install the CLI
+
+```sh
+pnpm add -D @equinor/fusion-framework-cli
+# or
+npm install --save-dev @equinor/fusion-framework-cli
+```
+
+### 2. Scaffold a New Portal
+
+Create a new directory for your portal and initialize your project:
+
+```sh
+mkdir my-fusion-portal && cd my-fusion-portal
+pnpm init
+```
+
+### 3. Create Required Files
+
+- `portal.manifest.ts`: Defines your portal's metadata and configuration.
+- `portal.schema.ts` (optional): Defines the schema for portal configuration.
+
+---
+
+## Portal Manifest
+
+The portal manifest (`portal.manifest.ts`) describes your portal's metadata, configuration, and capabilities. It is required for all portal templates. You may also define a schema file for advanced configuration validation.
+
+---
+
+## Commands
+
+### Command Overview
+
+The Fusion Framework CLI provides a suite of commands to support the full portal template lifecycle, from development to deployment. Below is an overview of all available commands with quick links to their detailed usage:
+
+- [Dev](#dev) — Start the portal development server for local development and testing.
+- [Build](#build) — Build your portal template using Vite.
+- [Pack](#pack) — Bundle your portal into a distributable archive for deployment.
+- [Upload](#upload) — Upload your portal bundle to the Fusion portal registry.
+- [Tag](#tag) — Tag a published portal template version in the Fusion portal registry.
+- [Manifest](#manifest) — Resolve and print the portal manifest for inspection or debugging.
+- [Schema](#schema) — Generate and validate the JSON schema for your Fusion portal application.
+
+---
+
+### Dev
+
+Start the portal development server for local development and testing.
+
+| Option              | Description                             | Default / Example    |
+| ------------------- | --------------------------------------- | -------------------- |
+| `--manifest <path>` | Path to the portal manifest file.       | `portal.manifest.ts` |
+| `--config <path>`   | Path to the portal config file.         | `portal.config.ts`   |
+| `--env <env>`       | Runtime environment for the dev server. | `local`              |
+| `--port <port>`     | Port for the development server.        | `3000`               |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal dev [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal dev
+pnpm fusion-framework-cli portal dev --port 4001 --manifest ./portal.manifest.ts
+```
+
+---
+
+### Build
+
+Build your portal template using Vite.
+
+| Option              | Description                        | Default / Example    |
+| ------------------- | ---------------------------------- | -------------------- |
+| `--manifest <path>` | Path to the portal manifest file.  | `portal.manifest.ts` |
+| `--env <env>`       | Runtime environment for the build. | `production`         |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal build [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal build
+pnpm fusion-framework-cli portal build --manifest ./portal.manifest.ts --env ci
+```
+
+---
+
+### Pack
+
+Bundle your portal into a distributable archive for deployment.
+
+| Option              | Description                       | Default / Example    |
+| ------------------- | --------------------------------- | -------------------- |
+| `--manifest <path>` | Path to the portal manifest file. | `portal.manifest.ts` |
+| `--schema <path>`   | Path to the portal schema file.   | `portal.schema.ts`   |
+| `--archive <name>`  | Name of the output archive file.  | `portal-bundle.zip`  |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal pack [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal pack
+pnpm fusion-framework-cli portal pack --archive my-portal.zip --schema ./portal.schema.ts
+```
+
+---
+
+### Upload
+
+Upload your portal bundle to the Fusion portal registry.
+
+| Option          | Description                              | Default / Example   |
+| --------------- | ---------------------------------------- | ------------------- |
+| `[bundle]`      | Path to the portal bundle archive.       | `portal-bundle.zip` |
+| `--name <name>` | Portal name (overrides bundle metadata). |                     |
+| `--token`       | Authentication token for Fusion.         |                     |
+| `--tenantId`    | Azure tenant ID for authentication.      |                     |
+| `--clientId`    | Azure client ID for authentication.      |                     |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal upload [bundle] [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal upload
+pnpm fusion-framework-cli portal upload my-portal.zip --name my-portal
+```
+
+---
+
+### Tag
+
+Tag a published portal template version in the Fusion portal registry.
+
+| Option/Argument   | Description                           | Default / Example |
+| ----------------- | ------------------------------------- | ----------------- |
+| `<tag>`           | Tag to apply (`latest` \| `preview`). |                   |
+| `--name <name>`   | Portal name.                          |                   |
+| `--version <ver>` | Version to tag.                       |                   |
+| `--token`         | Authentication token for Fusion.      |                   |
+| `--tenantId`      | Azure tenant ID for authentication.   |                   |
+| `--clientId`      | Azure client ID for authentication.   |                   |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal tag <tag> [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal tag latest --name my-portal --version 1.0.0
+pnpm fusion-framework-cli portal tag preview --name my-portal --version 1.1.0-beta
+```
+
+---
+
+### Manifest
+
+Resolve and print the portal manifest for inspection or debugging.
+
+| Option              | Description                                  | Default / Example    |
+| ------------------- | -------------------------------------------- | -------------------- |
+| `--manifest <path>` | Path to the portal manifest file.            | `portal.manifest.ts` |
+| `--env <env>`       | Runtime environment for manifest resolution. | `local`              |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal manifest [options]
+```
+
+**Examples:**
+```sh
+pnpm fusion-framework-cli portal manifest
+pnpm fusion-framework-cli portal manifest --manifest ./portal.manifest.ts --env ci
+```
+
+---
+
+### Schema
+
+Generate and validate the JSON schema for your Fusion portal application.
+
+| Option/Argument  | Description                                                           | Default / Example |
+| ---------------- | --------------------------------------------------------------------- | ----------------- |
+| `[schema]`       | Schema build file to use (e.g., `portal.schema[.env]?.[ts,js,json]`). |                   |
+| `-o, --output`   | Output file name (default: stdout).                                   | `stdout`          |
+| `-d, --debug`    | Enable debug mode for verbose logging.                                | `false`           |
+| `-v, --validate` | Validate the generated schema against a JSON file.                    |                   |
+| `--env <env>`    | Runtime environment for schema generation (supports dev).             |                   |
+
+**Usage:**
+```sh
+pnpm fusion-framework-cli portal schema [schema] [options]
+```
+
+**Examples:**
+```sh
+# Generate schema and print to stdout
+pnpm fusion-framework-cli portal schema
+
+# Generate schema and write to a file
+pnpm fusion-framework-cli portal schema --output portal.schema.json
+
+# Validate a config file against the generated schema
+pnpm fusion-framework-cli portal schema --validate my-config.json
+
+# Use a specific schema file and enable debug mode
+pnpm fusion-framework-cli portal schema portal.schema.prod.ts --debug
+```
+
+---
+
+## Troubleshooting & FAQ
+
+- **Manifest/config not found:** Ensure `portal.manifest.ts` exists in your project root.
+- **Build errors:** Check your Vite config and ensure all dependencies are installed.
+- **Authentication issues:** Make sure you have the correct permissions and tokens for uploading or tagging.
+- **Command help:** Run any command with `--help` for detailed usage and options.
+
+---
+
+For advanced configuration and authentication, see [Authentication](./auth.md).