Rover graph commands

These Rover commands are primarily for interacting with monolithic graphs that do not use federation. However, you can also use them to fetch a federated graph's API schema from Apollo Studio or via introspection.

Fetching a schema

Fetching from Apollo Studio

You can use Rover to fetch the current schema of any Studio graph and variant it has access to.

Run the graph fetch command, like so:

1
rover graph fetch my-graph@my-variant

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

Fetching via introspection

If you need to obtain the schema of a running GraphQL server or federated gateway, you can use Rover to execute an introspection query on it. This is especially helpful if you're developing a GraphQL server that doesn't define its schema via SDL, such as graphql-kotlin.

Use the graph introspect command, like so:

1
rover graph introspect http://example.com/graphql

The server must be reachable by Rover and it must have introspection enabled.

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, use the header multiple times. If the header includes any spaces, the pair must be quoted.

1
rover graph introspect http://example.com/graphql --header "Authorization: Bearer token329r"

Output format

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

1
rover graph introspect http://localhost:4000 | rover graph publish my-graph@dev --schema -

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

1
# Creates prod-schema.graphql or overwrites if it already exists
2
rover graph fetch my-graph@my-variant > prod-schema.graphql

Publishing a schema to Apollo Studio

You can use Rover to publish schema changes to one of your Apollo Studio graphs.

Use the graph publish command, like so:

1
rover graph publish my-graph@my-variant --schema ./schema.graphql

The argument my-graph@my-variant in the example above specifies the ID of the Studio graph you're publishing to, along with which variant you're publishing to.

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

Providing the schema

You provide your schema to Rover commands via the --schema option. The value is usually the path to a local .graphql or .gql file in SDL format.

If your schema isn't stored in a compatible file, you can provide - as the value of the --schema flag to instead accept an SDL string from stdin. This enables you to pipe the output of another Rover command (such as graph introspect), like so:

1
rover graph introspect http://localhost:4000 | rover graph publish my-graph@dev --schema -

Whenever possible, we recommend publishing a .graphql file directly instead of using introspection. An introspection result omits schema comments and most uses of directives.

Checking schema changes

Before you publish schema changes to Apollo Studio, 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 graph check command:

1
# using a schema file
2
rover graph check my-graph@my-variant --schema ./schema.graphql
3

4
# using piped input to stdin
5
rover graph introspect http://localhost:4000 | rover graph check my-graph --schema -

As shown, arguments and options are similar to graph publish.

To configure the behavior of schema checks (such as the time range of past operations to check against), see the documentation for schema checks.

Deleting a variant

You can delete a single variant of a graph by running rover graph delete:

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

This command prompts you for confirmation because the action is irreversible. You can bypass confirmation by passing the --confirm flag.

If you delete a federated variant with this command, it also deletes all of that variant's subgraphs. To delete a single subgraph while preserving the variant, see Deleting a subgraph.