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 's API schema from GraphOS or via introspection.

Fetching a schema

graph fetch

This command requires authenticating Rover with GraphOS.

You can use to fetch the current schema 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 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 schema of a running or federated gateway, you can use to execute an on it. This is especially helpful if you're developing a GraphQL server that doesn't define its schema 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 endpoint every second. Whenever the returned schema differs from the previously returned schema, 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 schema 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 schema 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 exists in but the variant doesn't, a new is be created on publish.

Providing the schema

You provide your schema to 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 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 schema comments and most uses of .

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, and options are similar to graph publish.

To configure the behavior of (such as the time range of past 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 schema 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 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 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 schema and your published schema.

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

Deleting a variant

graph delete

This command requires authenticating Rover with GraphOS.

You can delete a single of a 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 . To delete a single subgraph while preserving the variant, see Deleting a subgraph.

Previous
explain
Next
license
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company