Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio

Rover graph commands

Publish and retrieve your API schema


These commands are primarily for interacting with monographs that do not use federation. However, you can also use them to fetch a federated graph's API from GraphOS or via introspection.

Fetching a schema

graph fetch

This command requires authenticating Rover with GraphOS.

You can use to fetch the current of any graph and it has access to.

Run the graph fetch command, like so:

rover graph fetch my-graph@my-variant

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

You can omit @ and the name. If you do, uses the default variant, named current.

graph introspect

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

Use the graph introspect command, like so:

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

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

Watching for schema changes

If you pass --watch to rover graph introspect, introspects your GraphQL endpoint every second. Whenever the returned differs from the previously returned , outputs the updated schema.

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.

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 as input to other commands:

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:

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

For more on passing values via stdout, see Conventions.

Publishing a schema to GraphOS

graph publish

This command requires authenticating Rover with GraphOS.

You can use to publish changes to one of your GraphOS monographs.

Use the graph publish command, like so:

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

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

If the graph exists in but the variant doesn't, a new is be created on publish.

Providing the schema

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

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

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 . An introspection result omits comments and most uses of s.

For more on accepting input via stdin, see Conventions.

Validating schema changes

graph check

This command requires authenticating Rover with GraphOS.

Before you publish 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 graph check command:

# Using a schema file
rover graph check my-graph@my-variant --schema ./schema.graphql
# Using piped input to stdin
rover graph introspect http://localhost:4000 | rover graph check my-graph --schema -

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

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

If you don't want to wait for the check to complete, you can run the command with the --background flag. You can then look up the check's result in Apollo Studio on the Checks tab.

Running checks in CI

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

graph lint

This command requires authenticating Rover with GraphOS.

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

Example command
rover graph lint --schema ./schema.graphql my-graph@my-variant

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

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

Options include:

NameDescription
--schema

Required. The path to a local .graphql or .gql file, in SDL format.

Alternatively, you can provide -, in which case the command uses an string piped to stdin instead (see Using stdin).

--ignore-existing-lint-violations

If provided, the linter only flags violations that are present in the diff between your local and your published schema.

By default, this command flags all violations in your local .

Deleting a variant

graph delete

This command requires authenticating Rover with GraphOS.

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

# ⚠️ This action is irreversible!
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 with this command, it also deletes all of that 's s. To delete a single subgraph while preserving the variant, see Deleting a subgraph.

Previous
explain
Next
persisted-queries
Edit on GitHubEditForumsDiscord