Nitro CLI Reference

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#

Command	Purpose	Cloud
`compose`	Compose source schemas into a Fusion archive	No
`download`	Download gateway configuration from Nitro Cloud	Yes
`migrate`	Migrate v1 to v2 configuration files	No
`publish`	Publish a Fusion configuration to a stage	Yes
`run`	Start a local Fusion gateway	No
`settings set`	Configure composition settings in an archive	No
`upload`	Upload a source schema for later composition	Yes
`validate`	Validate a schema against a stage	Yes

Cloud Authentication Options#

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

Option	Description	Default
`--api-key <key>`	API key for authentication	`NITRO_API_KEY` env var

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#

Option	Description	Default
`--source-schema-file <path>` (alias: `-f`)	Path to a source schema file. Can be repeated.	Auto-discovers `.graphql`/`.graphqls` in working directory
`--archive <path>` (alias: `-a`)	Output path for the Fusion archive	`./gateway.far`
`--environment <name>` (alias: `--env`, `-e`)	Environment name for variable substitution	`ASPNETCORE_ENVIRONMENT` or `Development`
`--enable-global-object-identification`	Enable Relay-style global object identification	`false`
`--include-satisfiability-paths`	Include satisfiability diagnostic paths	`false`
`--watch`	Recompose on file changes	`false`
`--exclude-by-tag <tag>`	Exclude fields/types by tag. Can be repeated.	--
`--working-directory <path>` (alias: `-w`)	Working directory for resolving paths	Current directory

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#

Option	Description	Default
`--api-id <id>`	The API identifier	`NITRO_API_ID` env var
`--stage <name>`	The stage name	`NITRO_STAGE` env var
`--output-file <path>`	Output file path	`./gateway.far`

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#

Argument	Values	Description
`TARGET`	`subgraph-config`	Migration target

Options#

Option	Description	Default
`--working-directory <path>` (alias: `-w`)	Directory to scan for configuration files	Current directory

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#

Option	Description	Default
`--archive <path>` (alias: `-a`)	Pre-composed Fusion archive	--
`--source-schema <name@version>` (alias: `-s`)	Source schema identifier. Can be repeated.	--
`--source-schema-file <path>` (alias: `-f`)	Source schema file. Can be repeated.	--
`--api-id <id>`	The API identifier	`NITRO_API_ID` env var
`--stage <name>`	Target stage	`NITRO_STAGE` env var
`--tag <tag>`	Version tag	`NITRO_TAG` env var
`--working-directory <path>` (alias: `-w`)	Working directory	Current directory
`--source-metadata <json>`	JSON metadata about the source	--

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.

Option	Description	Default
`--api-id <id>`	The API identifier	`NITRO_API_ID` env var
`--stage <name>`	Target stage	`NITRO_STAGE` env var
`--tag <tag>`	Version tag	`NITRO_TAG` env var
`--wait-for-approval`	Wait for manual approval before proceeding	`false`
`--source-metadata <json>`	JSON metadata about the source	--

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

nitro fusion publish start#

Start composition for the deployment.

Option	Description	Default
`--request-id <id>`	Deployment request ID	Uses cached value from `begin`

nitro fusion publish start

nitro fusion publish validate#

Validate the configuration before committing.

Option	Description	Default
`--request-id <id>`	Deployment request ID	Uses cached value from `begin`
`--archive <path>` (alias: `-a`)	Fusion archive to validate	--

nitro fusion publish validate --archive gateway.far

nitro fusion publish commit#

Finalize the deployment.

Option	Description	Default
`--request-id <id>`	Deployment request ID	Uses cached value from `begin`
`--archive <path>` (alias: `-a`)	Fusion archive to deploy	--

nitro fusion publish commit --archive gateway.far

nitro fusion publish cancel#

Cancel the deployment.

Option	Description	Default
`--request-id <id>`	Deployment request ID	Uses cached value from `begin`

nitro fusion publish cancel

Orchestrated Workflow#

A typical advanced deployment follows this sequence:

nitro fusion publish begin -- reserve a deployment slot
nitro fusion publish start -- start composition
nitro fusion publish validate -- validate the configuration
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#

Argument/Option	Description	Default
`<ARCHIVE_FILE>` (required)	Path to the Fusion archive	--
`--port <number>` (alias: `-p`)	Port to bind	Random unused port

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#

Option	Description	Default
`--archive <path>` (alias: `-a`)	Fusion archive to modify	--
`--environment <name>` (alias: `--env`, `-e`)	Environment name for variable substitution	`ASPNETCORE_ENVIRONMENT` or `Development`

Available Settings#

Setting	Values	Description
`global-object-identification`	`true`, `false`	Enable Relay-style node queries
`cache-control-merge-behavior`	`ignore`, `include`, `include-private`	How to merge `@cacheControl` directives
`tag-merge-behavior`	`ignore`, `include`, `include-private`	How to merge `@tag` directives
`exclude-by-tag`	Comma-separated tags	Exclude fields/types by tag

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#

Option	Description	Default
`--api-id <id>`	The API identifier	`NITRO_API_ID` env var
`--tag <tag>`	Version tag	`NITRO_TAG` env var
`--source-schema-file <path>` (alias: `-f`)	Source schema file (required)	--
`--working-directory <path>` (alias: `-w`)	Working directory	Current directory
`--source-metadata <json>`	JSON metadata about the source	--

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#

Option	Description	Default
`--archive <path>` (alias: `-a`)	Fusion archive to validate	--
`--source-schema-file <path>` (alias: `-f`)	Source schema files. Can be repeated.	--
`--api-id <id>`	The API identifier	`NITRO_API_ID` env var
`--stage <name>`	Stage to validate against	`NITRO_STAGE` env var

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.

JSON

{
  "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.

JSON

{
  "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.

`preprocessor.inferShareable`#

Type: boolean (optional, defaults to false)

When true, composition automatically marks every field on this source schema that is resolvable by multiple source schemas as @shareable, skipping INVALID_FIELD_SHARING validation. Fields that are part of a @key, marked @internal or @inaccessible, or defined on the subscription type are not marked automatically.

Environment Variables#

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

Variable	Corresponding Option	Used By
`NITRO_API_ID`	`--api-id`	download, publish, upload, validate
`NITRO_API_KEY`	`--api-key`	download, publish, upload, validate
`NITRO_STAGE`	`--stage`	download, publish, validate
`NITRO_TAG`	`--tag`	publish, upload
`NITRO_FUSION_CONFIG_FILE`	`--archive`	publish
`NITRO_OUTPUT_FILE`	`--output-file`	download
`NITRO_REQUEST_ID`	`--request-id`	publish begin/start/validate/commit/cancel
`ASPNETCORE_ENVIRONMENT`	`--environment`	compose, settings set

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)

Edit this page on GitHub

Nitro CLI Reference

Installation#

npm (recommended)#

Homebrew (macOS)#

.NET tool#

Verify installation#

Commands Overview#

Cloud Authentication Options#

nitro fusion compose#

Syntax#

Options#

Examples#

nitro fusion download#

Syntax#

Options#

Examples#

nitro fusion migrate#

Syntax#

Arguments#

Options#

Behavior#

Examples#

nitro fusion publish#

Syntax#

Options#

Input Modes#

Sub-Commands for Advanced Orchestration#

nitro fusion publish begin#

nitro fusion publish start#

nitro fusion publish validate#

nitro fusion publish commit#

nitro fusion publish cancel#

Orchestrated Workflow#

nitro fusion run#

Syntax#

Options#

Examples#

nitro fusion settings set#

Syntax#

Options#

Available Settings#

Examples#

nitro fusion upload#

Syntax#

Options#

Examples#

nitro fusion validate#

Syntax#

Options#

Examples#

Schema Settings File Reference#

Fields#

name#

transports.http.url#

transports.http.clientName#

transports.subscriptions.transport#

extensions.nitro.apiId#

environments#

preprocessor.inferShareable#

Environment Variables#

Exit Codes#

`name`#

`transports.http.url`#

`transports.http.clientName`#

`transports.subscriptions.transport`#

`extensions.nitro.apiId`#

`environments`#

`preprocessor.inferShareable`#