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

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.

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).

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"

Auto-discover source schemas from a working directory:

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

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

Examples

Enable global object identification on an archive:

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

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