The Nitro CLI provides the nitro fusion command group for composing, validating, publishing, and running Fusion gateway configurations. Use these commands for local development workflows and for publishing configurations to Nitro Cloud.

Installation

npm (recommended)

npm install -g @chillicream/nitro

The npm package bundles platform-specific native binaries. Supported platforms: linux-x64, linux-musl-x64, linux-arm64, osx-x64, osx-arm64, win-x64, win-x86, win-arm64.

Homebrew (macOS)

brew install ChilliCream/tools/nitro-cli

.NET tool

Install globally:

dotnet tool install --global ChilliCream.Nitro.CommandLine

Or install per-project:

dotnet new tool-manifest
dotnet tool install ChilliCream.Nitro.CommandLine

Verify installation

nitro --version

Commands Overview

Cloud Authentication Options

Commands that interact with Nitro Cloud (download, publish, upload, validate) accept these global options:

If --api-key is not provided and no NITRO_API_KEY environment variable is set, the CLI uses the session from nitro login.

nitro fusion compose

Composes source schemas into a Fusion archive (.far file).

Syntax

nitro fusion compose [options]

Options

Each .graphqls file must have a companion -settings.json file (for example, schema.graphqls requires schema-settings.json). If no --source-schema-file is specified, the CLI scans the working directory for all .graphql and .graphqls files.

Examples

Compose from specific files:

nitro fusion compose \
  --source-schema-file ./Products/schema.graphqls \
  --source-schema-file ./Reviews/schema.graphqls \
  --archive gateway.far \
  --environment Development \
  --enable-global-object-identification

Auto-discover and compose all schemas in the current directory:

nitro fusion compose --archive gateway.far

Watch mode for local development:

nitro fusion compose --watch

Exclude fields tagged as experimental or internal:

nitro fusion compose \
  --exclude-by-tag experimental \
  --exclude-by-tag internal-only \
  --archive gateway.far

nitro fusion download

Downloads gateway configuration from Nitro Cloud.

Syntax

nitro fusion download [options]

Options

Examples

nitro fusion download \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg== \
  --stage production \
  --output-file gateway.far

nitro fusion migrate

Migrates configuration files from v1 to v2 format.

Syntax

nitro fusion migrate <TARGET> [options]

Arguments

Options

Behavior

The subgraph-config target converts subgraph-config.json files to the schema-settings.json format. The migration maps subgraph to name and http.baseAddress to transports.http.url. If a schema-settings.json file already exists in the target directory, the migration skips that directory.

Examples

Migrate all subgraph configs in the current directory:

nitro fusion migrate subgraph-config

Migrate configs in a specific directory:

nitro fusion migrate subgraph-config --working-directory ./subgraphs

nitro fusion publish

Publishes a Fusion configuration to a stage on Nitro Cloud. Three input modes are available (mutually exclusive).

Syntax

nitro fusion publish [options]

Options

Input Modes

Mode 1: Pre-composed archive. Publish an existing .far file with --archive.

nitro fusion publish \
  --archive gateway.far \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Mode 2: Source schema files. Compose and publish from local files with --source-schema-file.

nitro fusion publish \
  --source-schema-file ./Products/schema.graphqls \
  --source-schema-file ./Reviews/schema.graphqls \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Mode 3: Uploaded schema references. Reference previously uploaded schemas by name and version with --source-schema.

nitro fusion publish \
  --source-schema [email protected] \
  --source-schema [email protected] \
  --tag v1.0.0 \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Sub-Commands for Advanced Orchestration

For complex deployment scenarios such as blue-green deployments or manual validation gates, use the publish sub-commands.

nitro fusion publish begin

Request a deployment slot.

nitro fusion publish begin \
  --stage production \
  --tag v1.0.0 \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

nitro fusion publish start

Start composition for the deployment.

nitro fusion publish start

nitro fusion publish validate

Validate the configuration before committing.

nitro fusion publish validate --archive gateway.far

nitro fusion publish commit

Finalize the deployment.

nitro fusion publish commit --archive gateway.far

nitro fusion publish cancel

Cancel the deployment.

nitro fusion publish cancel

Orchestrated Workflow

A typical advanced deployment follows this sequence:

1. nitro fusion publish begin -- reserve a deployment slot
2. nitro fusion publish start -- start composition
3. nitro fusion publish validate -- validate the configuration
4. nitro fusion publish commit -- finalize the deployment

To abort at any point, run nitro fusion publish cancel.

nitro fusion run

Starts a local Fusion gateway from an archive file.

Syntax

nitro fusion run <ARCHIVE_FILE> [options]

Options

The gateway auto-opens a browser with the Nitro IDE. CORS is enabled, and GraphQL-Preflight and Authorization headers are propagated.

Examples

Start a gateway on a specific port:

nitro fusion run gateway.far --port 5000

Start a gateway on a random port:

nitro fusion run gateway.far

nitro fusion settings set

Modifies composition settings in a Fusion archive.

Syntax

nitro fusion settings set <SETTING_NAME> <SETTING_VALUE> [options]

Options

Available Settings

Examples

Enable global object identification:

nitro fusion settings set global-object-identification true --archive gateway.far

Configure cache control merging:

nitro fusion settings set cache-control-merge-behavior include --archive gateway.far

Exclude tagged fields:

nitro fusion settings set exclude-by-tag experimental,internal-only --archive gateway.far

nitro fusion upload

Uploads a source schema to Nitro Cloud for later composition.

Syntax

nitro fusion upload [options]

Options

Examples

Upload a source schema:

nitro fusion upload \
  --source-schema-file ./src/Products/schema.graphqls \
  --tag v1.2.3 \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Upload with a git commit SHA as the tag:

nitro fusion upload \
  --source-schema-file ./schema.graphqls \
  --tag $(git rev-parse --short HEAD) \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

nitro fusion validate

Validates a schema against a stage on Nitro Cloud. Two input modes are available (mutually exclusive).

Syntax

nitro fusion validate [options]

Options

Examples

Validate from source schema files:

nitro fusion validate \
  --source-schema-file ./Products/schema.graphqls \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Validate from an archive:

nitro fusion validate \
  --archive gateway.far \
  --stage production \
  --api-id QXBpCmcwMTk5MGUzNDVlMWU3MjMyYjc2MjYxYzFiNjRkMGQzYg==

Schema Settings File Reference

Each source schema requires a schema-settings.json file alongside its .graphqls schema file. This file configures the source schema name, transport settings, and per-environment variable substitutions.

{
  "name": "products-api",
  "transports": {
    "http": {
      "url": "{{API_URL}}"
    }
  },
  "environments": {
    "development": {
      "API_URL": "http://localhost:5110/graphql"
    },
    "production": {
      "API_URL": "https://api.example.com/graphql"
    }
  }
}

Fields

name

Type: string (required)

The unique source schema name used in composition. Must match the name used in builder.AddGraphQL("products-api").

transports.http.url

Type: string (required)

The URL template for the subgraph's GraphQL endpoint. Use {{VARIABLE_NAME}} for environment-specific substitution.

transports.http.clientName

Type: string (optional, defaults to "fusion")

The named HTTP client the gateway uses to communicate with this subgraph. Must match what the gateway configures via builder.Services.AddHttpClient("fusion").

transports.subscriptions.transport

Type: "sse" | "ws" (optional)

The transport protocol for real-time subscriptions. Defaults to "sse" (Server-Sent Events).

extensions.nitro.apiId

Type: string (optional)

The Nitro Cloud API identifier for this subgraph. Required when using Nitro Cloud features like upload or publish.

environments

Type: object (optional)

Per-environment variable substitutions. The active environment is selected via the --environment flag during composition or via the ASPNETCORE_ENVIRONMENT environment variable.

{
  "environments": {
    "development": {
      "API_URL": "http://localhost:5110/graphql"
    },
    "staging": {
      "API_URL": "https://staging.example.com/graphql"
    },
    "production": {
      "API_URL": "https://api.example.com/graphql"
    }
  }
}

When composing with --environment staging, all {{API_URL}} placeholders resolve to the staging URL.

Environment Variables

The Nitro CLI reads these environment variables as defaults for their corresponding options.

Set these in CI/CD pipelines to avoid passing values as command-line arguments.

Exit Codes

• 0 -- success
• Non-zero -- failure (error details printed to stderr)