The nitro fusion commands manage Fusion configurations. A Fusion configuration is the composed gateway artifact built from one or more source schemas. Once published to a stage, the gateway loads it and starts serving the federated graph.

[!NOTE] For using these commands in CI/CD pipelines (uploading source schemas, publishing configurations, validating pull requests), see Deployment and CI/CD.

nitro fusion upload

Upload a source schema for a later composition. The schema is stored on the Nitro backend under the given API and tag and can be referenced by name from a subsequent nitro fusion publish call (via --source-schema).

nitro fusion upload \
  --api-id "<api-id>" \
  --tag "<tag>" \
  --source-schema-file "<source-schema-file>"

Options

--source-schema-file accepts either a schema file or a directory. In both cases, a schema-settings.json file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory).

Examples

Upload a single source schema:

nitro fusion upload \
  --api-id "<api-id>" \
  --tag "v1" \
  --source-schema-file ./products/schema.graphqls

nitro fusion publish

Since: 16.6.0, Nitro: 10.3.0

Publish a Fusion configuration to a stage.

nitro fusion publish \
  --api-id "<api-id>" \
  --stage "<stage>" \
  --tag "<tag>" \
  --source-schema products

Options

--source-schema-file accepts either a schema file or a directory. In both cases, a schema-settings.json file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory).

Examples

Compose and publish from previously uploaded source schemas:

nitro fusion publish \
  --api-id "<api-id>" \
  --stage "dev" \
  --tag "v1" \
  --source-schema products \
  --source-schema reviews

Compose and publish from local source schema files in one step:

nitro fusion publish \
  --api-id "<api-id>" \
  --stage "dev" \
  --tag "v1" \
  --source-schema-file ./products/schema.graphqls \
  --source-schema-file ./reviews/schema.graphqls

Publish a pre-composed archive:

nitro fusion publish \
  --api-id "<api-id>" \
  --stage "dev" \
  --tag "v1" \
  --archive ./gateway.far

Advanced: multi-step publish

Reach for these commands only when nitro fusion publish cannot model your pipeline, for example when validation must run in one CI job and the deploy must run in a separate, manually approved job. For everything else, prefer nitro fusion publish. The subcommands below split the same flow into individual steps, which is more error-prone and harder to monitor.

A multi-step publish is driven by a single request ID. begin allocates a deployment slot and prints a request ID, every following step references that ID (either explicitly via --request-id or implicitly via local state that the CLI caches between commands in the same job). The standard order is begin → start → validate → commit. cancel releases the slot at any time before commit.

nitro fusion publish begin

Begin a Fusion configuration publish by requesting a deployment slot for a stage. The returned request ID identifies the publish for every subsequent step.

nitro fusion publish begin \
  --api-id "<api-id>" \
  --tag "<tag>" \
  --stage "<stage>"

nitro fusion publish start

Mark the publish as started. After this step the deployment is in flight and the configuration is being applied to the gateway.

nitro fusion publish start --request-id "<request-id>"

nitro fusion publish validate

Validate a composed Fusion archive against everything currently published to the stage targeted by the request.

nitro fusion publish validate \
  --request-id "<request-id>" \
  --archive "<archive-file>"

nitro fusion publish commit

Commit the Fusion configuration, finalizing the publish. After this step the new configuration is live on the stage.

nitro fusion publish commit \
  --request-id "<request-id>" \
  --archive "<archive-file>"

nitro fusion publish cancel

Cancel an in-progress publish and release the deployment slot. Run this from the failure branch of any job between begin and commit.

nitro fusion publish cancel --request-id "<request-id>"

nitro fusion validate

Validate a Fusion configuration against a stage. Composes the supplied source schemas (or uses a pre-composed archive) and runs the same checks as publish without requesting a deployment slot.

nitro fusion validate \
  --api-id "<api-id>" \
  --stage "<stage>" \
  --archive "<archive-file>"

Options

--source-schema-file accepts either a schema file or a directory. In both cases, a schema-settings.json file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory).

Examples

Validate by composing source schemas on the fly:

nitro fusion validate \
  --api-id "<api-id>" \
  --stage "dev" \
  --source-schema-file ./products/schema.graphqls \
  --source-schema-file ./reviews/schema.graphqls

Validate a pre-composed archive:

nitro fusion validate \
  --api-id "<api-id>" \
  --stage "dev" \
  --archive ./gateway.far

nitro fusion download

Download the most recent gateway configuration of a stage to a local archive file.

nitro fusion download \
  --api-id "<api-id>" \
  --stage "<stage>" \
  --output-file "<output-file>"

Options

Examples

Download the live dev configuration:

nitro fusion download \
  --api-id "<api-id>" \
  --stage "dev" \
  --output-file ./gateway.far

nitro fusion compose

Compose multiple source schemas into a single composite schema and write the result to a Fusion archive.

When --archive points at an existing archive, compose works incrementally: source schemas already in the archive are carried forward, a --source-schema-file whose name matches an existing source schema overrides it, and --remove-source-schema drops one. So removing a source schema is --remove-source-schema <name>, and replacing or renaming one is --remove-source-schema <oldName> together with --source-schema-file <newFile>.

nitro fusion compose \
  --source-schema-file "<source-schema-file>" \
  --archive "<archive-file>"

Options

--source-schema-file accepts either a schema file or a directory. In both cases, a schema-settings.json file is expected to sit next to the schema file (when a directory is given, both files must be inside that directory).

Local schema files do not use --source-schema-settings-file. For a local file, Nitro derives the companion settings path from the schema file. For example, ./inventory/schema.graphqls uses ./inventory/schema-settings.json.

For remote sources, repeat --source-schema-url and --source-schema-settings-file the same number of times. Nitro pairs them by occurrence: the first URL uses the first settings file, the second URL uses the second settings file, and so on. Keep each pair adjacent so the relationship remains visible in scripts.

The paired settings file selects the acquisition protocol. An absent apolloFederationSupport marker makes Nitro GET raw SDL from the exact URL. Exact "1.0" and "2.0" markers make Nitro POST an Apollo _service { sdl } query. See Getting the Subgraph Schema for the settings shape and protocol details.

Examples

Compose a gateway from two source schemas:

nitro fusion compose \
  --source-schema-file ./products/schema.graphqls \
  --source-schema-file ./reviews/schema.graphqls \
  --archive ./gateway.far \
  --env "dev"

Compose two remote schemas and one local schema:

nitro fusion compose \
  --source-schema-url https://products.example.com/graphql \
  --source-schema-settings-file ./products/schema-settings.json \
  --source-schema-url https://reviews.example.com/graphql \
  --source-schema-settings-file ./reviews/schema-settings.json \
  --source-schema-file ./inventory/schema.graphqls \
  --archive ./gateway.far

After a successful composition, Nitro prints:

✅ Composite schema written to '/absolute/path/to/gateway.far'.

Auto-discover source schemas from a working directory:

nitro fusion compose \
  --working-directory ./subgraphs \
  --archive ./gateway.far

Remove a source schema and recompose:

nitro fusion compose \
  --archive ./gateway.far \
  --remove-source-schema reviews

Replace or rename a source schema (drop the old, add the new):

nitro fusion compose \
  --archive ./gateway.far \
  --remove-source-schema reviews \
  --source-schema-file ./reviews-v2/schema.graphqls

In watch mode, Nitro observes local schema directories and paired remote settings files. A watched change triggers recomposition and fetches the remote schemas again. Nitro does not poll remote URLs.

nitro fusion settings set

Set a Fusion composition setting on a Fusion archive. Use this to flip composition-level toggles after a composition has been produced, without recomposing from sources.

nitro fusion settings set <SETTING_NAME> <SETTING_VALUE> \
  --archive "<archive-file>"

Arguments

Options

Available Settings

Examples

Enable global object identification on an archive:

nitro fusion settings set global-object-identification "true" \
  --archive ./gateway.far \
  --env "dev"

After a successful update, Nitro prints:

Composed new configuration.

For examples of node resolution, shareable runtime type routing, and tag exclusion, see Fusion CLI.

nitro fusion source-schema init

Create the schema-settings.json file that a source schema needs for composition. The settings file is written next to the schema file it belongs to, under the name composition looks for, so nitro fusion compose picks it up without further configuration.

Running the command against an existing settings file updates the values you pass and preserves every other setting in the file, which makes it safe to re-run from a pipeline. The one exception is --kind, which owns the settings described under Source schema kinds.

nitro fusion source-schema init [options]

Options

--name and --url are only required when the settings file does not exist yet, since an existing file already carries both. On an interactive terminal the command asks for whichever of the two you did not pass. Everywhere else, including CI, omitting one fails rather than guessing a value.

Both --url and --dev-url accept {{VARIABLE_NAME}} placeholders, which composition resolves against the environments section of the settings file.

Source schema kinds

--kind describes the server behind the source schema, which decides what the file declares beyond the name and transport URL.

--kind owns these settings: passing it removes the settings belonging to the other kinds, so switching a source schema from one kind to another leaves no stale markers behind. Omit --kind to leave them untouched.

--apollo-federation-version defaults to 2.0 for a source schema that is not yet marked as an Apollo Federation subgraph. For one that already is, the version already in the file is kept unless you pass a new one.

A source schema marked apollo-federation that composition fetches over HTTP (via --source-schema-url on nitro fusion compose) is retrieved through Apollo Federation's _service field. A source schema read from a local file is read as it is on disk, and the marker only affects directive semantics.

Where the file is written

The target path is resolved in this order:

1. --settings-file, when given.
2. Next to --source-schema-file as <schema-file-name>-settings.json. A path that is not named like a schema file counts as a directory, whether or not it exists yet: the schema file inside it determines the name, and schema-settings.json is used when it holds none.
3. schema-settings.json in the working directory.

Examples

Create settings for a subgraph next to its schema file:

nitro fusion source-schema init \
  --name "products" \
  --source-schema-file ./products/schema.graphqls \
  --url "https://products.example.com/graphql"

This writes ./products/schema-settings.json:

{
  "name": "products",
  "transports": {
    "http": {
      "url": "https://products.example.com/graphql"
    }
  }
}

Create settings for an Apollo Federation subgraph:

nitro fusion source-schema init \
  --name "reviews" \
  --source-schema-file ./reviews/schema.graphqls \
  --url "https://reviews.example.com/graphql" \
  --kind apollo-federation \
  --apollo-federation-version 2.0

Point an existing settings file at a new URL without touching its other settings:

nitro fusion source-schema init \
  --source-schema-file ./products/schema.graphqls \
  --url "https://products.staging.example.com/graphql"

nitro fusion run

Start a Fusion gateway locally with the specified archive. Useful for smoke-testing a composed archive before publishing. Only supports Fusion v2.

nitro fusion run "<archive-file>"

Arguments

Options

Examples

Run a gateway on port 5000:

nitro fusion run ./gateway.far --port 5000