Rover subgraph Commands

A subgraph is a graph that contributes to the composition of a federated supergraph:

Rover commands that interact with subgraphs begin with rover subgraph.

Fetching a subgraph schema

These commands enable you to fetch the schema for a single subgraph in a supergraph. To instead fetch the API schema for a supergraph, use rover graph fetch. To fetch the supergraph schema, use rover supergraph fetch.

subgraph fetch

This command requires authenticating Rover with GraphOS.

You can use Rover to fetch the current schema of any subgraph that belongs to a graph variant or schema proposal that Rover has access to.

Run the subgraph fetch command, like so:

1rover subgraph fetch my-graph@my-variant --name accounts

The argument my-graph@my-variant in the example above is a graph ref that specifies the ID of the Studio graph you're fetching from, along with which variant you're fetching.

The --name option is required.** It specifies which subgraph you're fetching the schema for.

Fetch subgraph schemas from proposals

To fetch a subgraph schema from a schema proposal, use the proposal's ID instead of a variant name like so:

1rover subgraph fetch my-graph@p-101 --name accounts

A proposal's ID is always prefixed with p- and followed by a number. You can find the proposal ID in the proposal's URL in GraphOS Studio. For example, a proposal with the following URL has an ID of p-101.

https://studio.apollographql.com/graph/Example-supergraph/proposal/p-101/home

subgraph introspect

If you need to obtain a running subgraph's schema, you can use Rover to execute an enhanced introspection query on it. This is especially helpful if the subgraph doesn't define its schema via SDL (as is the case with graphql-kotlin).

Use the subgraph introspect command, like so:

1rover subgraph introspect http://localhost:4001

The subgraph must be reachable by Rover. The subgraph does not need to have introspection enabled.

Unlike a standard introspection query, the result of rover subgraph introspect does include certain directives (specifically, directives related to federation like @key). This is possible because the command uses a separate introspection mechanism provided by the Apollo Federation subgraph specification.

Watching for schema changes

If you pass --watch to rover subgraph introspect, Rover introspects your subgraph continuously. Whenever the returned schema differs from the previously returned schema, Rover outputs the updated schema. This is most useful when combined with the --output <OUTPUT_FILE> argument which will write the introspection response out to a file whenever its contents change.

Including headers

If the endpoint you're trying to reach requires HTTP headers, you can use the --header (-H) flag to pass key:value pairs of headers. If you have multiple headers to pass, provide the flag multiple times. If a header includes any spaces, the pair must be quoted.

1rover subgraph introspect http://localhost:4001 --header "Authorization: Bearer token329r"

Output format

1rover subgraph introspect http://localhost:4001\
2  | rover subgraph publish my-graph@dev\
3  --schema - --name accounts\
4  --routing-url https://my-running-subgraph.com/api

By default, both subgraph fetch and subgraph introspect output fetched SDL to stdout. This is useful for providing the schema as input to other Rover commands:

1rover subgraph introspect http://localhost:4000 | rover subgraph check my-graph --schema -

You can also save the output to a local .graphql file like so:

1# Creates accounts-schema.graphql or overwrites if it already exists
2rover subgraph introspect http://localhost:4000 --output accounts-schema.graphql

For more on passing values via stdout, see Using stdout.

Listing subgraphs in a supergraph

subgraph list

This command requires authenticating Rover with GraphOS.

You can use the subgraph list to list all of a particular supergraph's available subgraphs in GraphOS:

1rover subgraph list my-supergraph@staging

This command lists all subgraphs for the specified variant, including their routing URLs and when they were last updated (in local time). A link to view this information in GraphOS Studio is also provided.

1Subgraphs:
2
3+----------+-------------- --------------+----------------------------+
4| Name     | Routing Url                 | Last Updated               |
5+----------+-----------------------------+----------------------------+
6| reviews  | https://reviews.my-app.com  | 2020-10-21 12:23:28 -04:00 |
7+----------+----------------------------------------+-----------------+
8| books    | https://books.my-app.com    | 2020-09-20 13:58:27 -04:00 |
9+----------+----------------------------------------+-----------------+
10| accounts | https://accounts.my-app.com | 2020-09-20 12:23:36 -04:00 |
11+----------+----------------------------------------+-----------------+
12| products | https://products.my-app.com | 2020-09-20 12:23:28 -04:00 |
13+----------+----------------------------------------+-----------------+
14
15View full details at https://studio.apollographql.com/graph/my-supergraph/service-list

Publishing a subgraph schema to GraphOS

subgraph publish

This command requires authenticating Rover with GraphOS.

You can use Rover to publish schema changes to a subgraph that belongs to a supergraph variant or schema proposal that Rover has access to.

Use the subgraph publish command, like so:

1rover subgraph publish my-supergraph@my-variant \
2  --schema "./accounts/schema.graphql" \
3  --name accounts \
4  --routing-url "https://my-running-subgraph.com/api"

The argument my-supergraph@my-variant in the example above is a graph ref that specifies the ID of the GraphOS graph you're publishing to, along with which variant you're publishing to.

Options include:

Running checks before publishing

Use the --check flag to run all configured schema checks and then publish in a single command. If any checks fail, the publish is aborted and no schema changes are pushed to the registry.

Running check and publish as two separate commands introduces two risks:

• Human error — You must type or paste both commands with identical arguments. A mismatched --schema path, --name, or graph ref means you could publish a schema that was never actually checked.

• Race conditions — Another team member could publish a change between your check and your publish, so the check result no longer reflects the state of the subgraph at publish time.

--check eliminates both risks by treating the check and publish as one atomic operation.

The --check flag honors all schema check settings configured for your graph variant in GraphOS Studio—including linting rules, operation checks, and any other check configurations—exactly as a standalone rover subgraph check would.

To illustrate the difference, here is the previous two-step approach:

1# Step 1: check
2rover subgraph check my-graph@current --schema ./schema.graphql --name accounts
3
4# Step 2: publish (only safe if nothing changed between the two commands)
5rover subgraph publish my-graph@current --schema ./schema.graphql --name accounts \
6  --routing-url "https://my-running-subgraph.com/api"

With --check, both steps happen in one command:

1rover subgraph publish my-graph@current --schema ./schema.graphql --name accounts \
2  --routing-url "https://my-running-subgraph.com/api" --check

If all checks pass, Rover publishes the subgraph schema and then waits for the launches it triggers. For details, see Waiting for launches. If any check fails, Rover prints the check output and exits without publishing. A failed check fails with error E043, as it does for subgraph check, with the message Schema checks must pass before publishing. Fix the check failures above and try again. With --format json, data is the check result, in the same shape as subgraph check's, and json_version is "3".

--include-contract-checks applies to the check that --check runs, as it does for subgraph check, and also to the launches the publish waits for.

--background doesn't apply to a publish, because --check always waits for the check: the check decides whether the publish happens. subgraph publish accepts --background for compatibility with earlier versions of Rover, ignores it, and warns:

1Warning: `--background` has moved to `rover subgraph check --background`, and will be removed from `rover subgraph publish` in a future version. It has no effect here: `publish --check` always waits for the check, because the check decides whether the publish happens.

For details on configuring checks (time range, operation thresholds, linting rules), see the subgraph check section.

Waiting for launches

When a publish changes the supergraph schema, it triggers a launch on the variant, and the launch can trigger launches on downstream contract variants. Rover waits for the triggered launch and every downstream contract-variant launch to finish before it exits. The wait is bounded by --checks-timeout (or the APOLLO_CHECKS_TIMEOUT_SECONDS environment variable), which defaults to 300 seconds. With --check, the check and the launch each get their own wait. If the launch wait times out, Rover fails with error E065. The schema is already published and the launch may still finish in GraphOS. With --format json, data still includes the publish response, with launch_status null, because Rover stopped waiting before it learned the outcome.

If the publish triggered downstream launches, Rover reports them on stderr:

1Triggered downstream launches for 2 contract variants: mobile, partner-api.
2View launch details at: https://studio.apollographql.com/graph/my-graph/launches/launch-1

If a downstream contract-variant launch fails, Rover prints a warning and exits successfully:

1Warning: The publish succeeded, but a downstream contract launch failed: mobile. Pass --include-contract-checks to make this fail the command.
2View launch details at: https://studio.apollographql.com/graph/my-graph/launches/launch-2

With --format json, the failed launch's status is FAILED in downstream_launches, and error is null.

If the variant's own launch fails, or a downstream launch fails and you passed --include-contract-checks, Rover reports which one failed and exits with error E047:

1The publish succeeded, but the launch itself failed.
2View launch details at: https://studio.apollographql.com/graph/my-graph/launches/launch-1

The subgraph schema is still published. With --format json, data keeps the full publish response alongside the E047 error.

With --format json, data includes the launch results. For example, a publish that triggered a launch and one downstream contract-variant launch, both completed:

1{
2  "json_version": "1",
3  "data": {
4    "api_schema_hash": "123456",
5    "supergraph_was_updated": true,
6    "subgraph_was_created": false,
7    "subgraph_was_updated": true,
8    "launch_url": "https://studio.apollographql.com/graph/my-graph/launches/launch-1",
9    "launch_cli_copy": null,
10    "launch_status": "COMPLETED",
11    "launch_superseded": false,
12    "downstream_launches": [
13      {
14        "graph_id": "my-graph",
15        "variant_name": "mobile",
16        "status": "COMPLETED",
17        "superseded": false,
18        "url": "https://studio.apollographql.com/graph/my-graph/launches/launch-2"
19      }
20    ],
21    "success": true
22  },
23  "error": null
24}

The launch fields are:

• launch_url: the Studio URL of the triggered launch, or null if the publish triggered none

• launch_cli_copy: GraphOS's description of the launch, or null

• launch_status: the launch's final status, such as COMPLETED or FAILED, or null

• launch_superseded: true if a later publish to the same variant superseded the launch

• downstream_launches: one entry per triggered contract-variant launch, with graph_id, variant_name, status, superseded, and url

For how this differs from earlier versions of Rover, see Upgrading to Rover 1.0.

Creating variants

You can use the subgraph publish command to create a new variant, but not a new graph.

• If the graph exists in the graph registry but the variant does not, a new variant is created on publish.

• If the graph doesn't exist, the command fails.

Validating subgraph schema changes

subgraph check

This command requires authenticating Rover with GraphOS.

Before you publish subgraph schema changes to GraphOS, you can check those changes to confirm that you aren't introducing breaking changes to your application clients.

To do so, you can run the subgraph check command:

1# using a schema file
2rover subgraph check my-graph@my-variant --schema ./schema.graphql --name accounts
3
4# using piped input to stdin
5rover subgraph introspect http://localhost:4000 \
6  | rover subgraph check my-graph@my-variant \
7  --schema - --name accounts

To configure schema check defaults for every check run on a graph variant, use check configurations in GraphOS Studio.

To override the default check configuration for a single check run, see the validation period and threshold values options below.

Options

Running checks in CI

If you're running schema checks in CI, you might want to pass the --background flag to rover subgraph check. This flag instructs Rover to initiate schema checks but not await their result. If you've connected GraphOS Studio to your GitHub repository, the integration detects the checks execution and adds a status to the associated pull request.

Validation period

By default, schema checks compare your changes against the operations seen in the last seven days, or whatever default you've configured in GraphOS Studio. Use --validation-period to override that default setting:

1rover subgraph check my-graph@my-variant \
2  --schema ./schema.graphql \
3  --name accounts \
4  --validation-period=2w

Valid durations are any combination of units supported by humantime, such as months/M, weeks/w, days/d, min/m, and sec/s. Values that contain spaces must be quoted:

• 2w (no quotes needed)

• "1month 2weeks" (quoted because of the space)

Threshold values

Use --query-count-threshold and --query-percentage-threshold to ignore historical operations that are rare—for example, to safely remove a field still used only by an old, low-traffic client.

• --query-count-threshold: Only check against operations executed at least this many times within the validation period.

• --query-percentage-threshold: Only check against operations that account for at least this percentage of total operation volume (e.g., 3 for 3%).

If you provide both flags, an operation must meet or exceed both thresholds to be included.

1rover subgraph check my-graph@my-variant \
2  --schema ./schema.graphql \
3  --name accounts \
4  --validation-period=5d \
5  --query-count-threshold=5 \
6  --query-percentage-threshold=3

Check output

Rover prints a section for each check task that ran, such as Build Check [PASSED]: and Operation Check [PASSED]:. The Build Check and Operation Check sections appear even when the check found no schema changes.

If your graph has contract variants, the output ends with a Downstream Check section that summarizes the contract variants checked:

1Downstream Check [PASSED]:
2Checked 2 contract variants, all passed.
3View downstream check details at: https://studio.apollographql.com/graph/my-graph/checks/downstream

The summary line is one of:

• No contract variants configured for this graph.

• Checked N contract variants, all passed.

• Checked N contract variants. (when not every contract variant passed)

A contract variant can be configured to block its source variant's checks. If a blocking contract variant's check fails, the summary names it. By default, subgraph check passes or fails with the overall GraphOS result for the check, and fails with error E043 when that result is a failure. Pass --include-contract-checks to fail with E043 whenever a blocking contract variant's own check has failed, even if the overall GraphOS result says the check passed:

1Downstream Check [FAILED]:
2The downstream check task has encountered check failures for at least this blocking downstream variant: mobile.
3View downstream check details at: https://studio.apollographql.com/graph/my-graph/checks/downstream

A failed check on a non-blocking contract variant appears in the output but doesn't fail the command.

Without --include-contract-checks, a blocking contract variant's failed check can appear under a passing Downstream Check [PASSED]: heading, when the overall GraphOS result is a pass. The command then exits successfully.

With --format json, check output uses json_version "3". The downstream task lists each contract variant in variants, with graph_id, variant_name, blocking, fails_upstream_workflow, and status:

1{
2  "json_version": "3",
3  "data": {
4    "core_schema_modified": false,
5    "tasks": {
6      "downstream": {
7        "task_status": "FAILED",
8        "target_url": "https://studio.apollographql.com/graph/my-graph/checks/downstream",
9        "variants": [
10          {
11            "graph_id": "my-graph",
12            "variant_name": "mobile",
13            "blocking": true,
14            "fails_upstream_workflow": null,
15            "status": "FAILED"
16          }
17        ]
18      }
19    },
20    "success": false
21  },
22  "error": {
23    "message": "The changes in the schema you proposed caused downstream checks to fail.",
24    "code": "E043"
25  }
26}

For what changed from json_version "2", see Upgrading to Rover 1.0.

subgraph lint

This command requires authenticating Rover with GraphOS.

You can run the GraphOS schema linter against your local subgraph schema to identify any violations of formatting and naming best practices:

1rover subgraph lint --name products --schema ./products-schema.graphql my-graph@my-variant

The argument my-graph@my-variant in the example above is a graph ref that specifies the ID of the graph you're comparing your schema changes against, along with which variant you're comparing against.

Schema linting also runs as one of the checks included in subgraph check. Use this command to perform one-off linting.

Options include:

Previewing a graph

subgraph preview

This command requires authenticating Rover with GraphOS.

Always preview your supergraph schema before publishing subgraph changes to ensure successful composition without affecting your production graph.

Run the subgraph preview command:

1rover subgraph preview my-graph@my-variant

The argument my-graph@my-variant in the preceding example is a graph ref that specifies the ID of the graph and variant whose subgraphs you want to use for the preview.

By default, subgraph preview composes the variant's subgraphs exactly as they're currently published. Use --subgraph-changes to preview the effect of hypothetical subgraph changes first (see Previewing subgraph changes below). You can also provide the --include-tag/--exclude-tag/--hide-unreachable-types options to preview a contract filter on top of composition.

Preview builds run asynchronously on GraphOS. By default, Rover starts the build and polls its status until it completes, then prints the resulting schema. For details, see Running previews asynchronously.

Options

1--include-tag foo --include-tag bar

1--exclude-tag foo --exclude-tag bar

Previewing subgraph changes

Use --subgraph-changes to preview what composition produces if you change or remove one or more subgraphs first, without publishing those changes. Provide a YAML file with a subgraphs map keyed by subgraph name:

1subgraphs:
2  foo:
3    routing_url: https://example.com  # optional; omit to keep the existing URL
4    schema:
5      file: ./foo.graphql              # or `sdl: "type Query { ... }"` inline
6  bar:
7    remove: true

1rover subgraph preview my-graph@my-variant --subgraph-changes ./changes.yaml

Each subgraph entry can set:

• routing_url: a hypothetical new routing URL for the subgraph. Omit to keep the subgraph's currently published URL.

• schema: a hypothetical new schema for the subgraph, either file: <path> (a local .graphql/.gql file) or sdl: "<inline SDL>". Omit to keep the subgraph's currently published schema.

• remove: true: Preview composition as if the subgraph had been removed. Don't combine with routing_url or schema.

Every subgraph entry must set at least one of routing_url, schema, or remove: true. Subgraphs you don't mention in the file compose exactly as they're currently published.

Running previews asynchronously

For long-running preview builds, use --async to start the build and return a build ID immediately. This approach helps large schemas avoid local timeouts.

1rover subgraph preview my-graph@my-variant --subgraph-changes ./changes.yaml --async

Check the build status later with --build-id:

1rover subgraph preview my-graph@my-variant --build-id <BUILD_ID>

By default (without --async), Rover polls the build's status until it completes or APOLLO_CHECKS_TIMEOUT_SECONDS passes. If Rover times out, your build may still complete in the background. Check your build's status later with --build-id.

Deleting a subgraph

subgraph delete

This command requires authenticating Rover with GraphOS.

You can delete a single subgraph from a federated variant by running rover subgraph delete:

1# ⚠️ This action is irreversible!
2rover subgraph delete my-graph@my-variant --name subgraph-to-delete

Before deleting, Rover previews the deletion: it composes the variant without the subgraph and prints any build errors the deletion would cause, without changing anything. It then prompts you for confirmation because the action is irreversible. The preview polls until composition finishes or APOLLO_CHECKS_TIMEOUT_SECONDS passes.

Pass --confirm to skip both the preview and the confirmation prompt.

To delete an entire federated graph instead of a single subgraph, see Deleting a variant.