Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Configuring Rover

Configuration guide for Rover CLI with GraphOS

Authenticating with GraphOS

1. Obtain an API key

All commands that communicate with GraphOS require an API key to do so. supports two types of API keys: personal API keys and graph API keys.

  • On your local development machine, use a personal API key.
  • In shared environments like CI, use a API key.

Learn how to obtain an API key.

2. Provide the API key to Rover

You can provide your API key to Rover either via a Rover command (recommended for local development) or by setting an environment variable (recommended for automation and CI).

If you provide an API key via both methods, the environment variable takes precedence.

Via the auth command

You can provide your API key to Rover by running the following command:

rover config auth

This method is recommended for local development. If you have more than one API key you want to use with Rover, you can assign those keys to different configuration profiles.

The auth command is interactive to prevent your API key from appearing in your terminal command history. Because it's interactive, we recommend using an environment variable in automated environments such as CI.

With an environment variable

You can provide your API key to Rover by setting it as the value of the APOLLO_KEY environment variable. This method is recommended for automated environments such as CI.

Configuration profiles

You can create multiple configuration profiles in Rover. Each configuration profile has its own associated API key, so you can use different configuration profiles when interacting with different .

To specify which configuration profile to use for a particular command, use the --profile flag:

rover graph check my-company@prod --profile work

If you don't specify a configuration profile for a command, Rover uses the default profile (named default).

To view all commands for working with configuration profiles, run the following command:

rover config --help

Learn more about rover config commands.


Rover supports the following levels of logging, in descending order of severity:

  • error
  • warn
  • info
  • debug
  • trace

By default, Rover logs error, warn, and info messages. You can configure this behavior for a command by setting its minimum log level with the --log flag:

rover graph check my-graph@prod --schema ./schema.graphql --log debug

If Rover log messages are unhelpful or unclear, please leave us feedback in an issue on GitHub!

Configuring output

By default, Rover prints the main output of its commands to stdout in plaintext. It also prints a descriptor for that output to stderr if it thinks it's being operated by a human (it checks whether the terminal is TTY).

For more on stdout, see Conventions.

Every Rover command supports two options for configuring its output behavior:

JSON output

The --format option was added in Rover v0.11.0. Earlier versions of Rover use the --output option to set output format.

Current versions of Rover still support using --output this way, but that support is deprecated and will be removed in a future release.

For more programmatic control over Rover's output, you can pass --format json to any command. Rover JSON output has the following minimal structure:

"json_version": "1",
"data": {
"success": true
"error": null
"json_version": "1",
"data": {
"success": false
"error": {
"message": "An unknown error occurred.",
"code": null

As shown in error_example above, some Rover errors have a null error code. Despite this, your scripts should match on particular errors based on their code instead of their message (message strings are subject to change without bumping json_version).

If you frequently encounter un-coded errors, please submit an issue.

JSON output fields

Name /


Indicates the version of the JSON output's structure. A script can check this value to detect breaking changes.

Non-breaking additions might be made to Rover's JSON structure without incrementing json_version.



Represents the command's result.

Always contains at least a success boolean . Other present fields depend on the command.

Note that error might be present even if data.success is true. Certain commands (e.g., subgraph publish) might result in composition errors even if the command's primary action (e.g., publishing the schema to Apollo) succeeds. See Command-specific JSON output.


Object | null

Represents any errors that occurred during the command's execution (or null if no errors occurred).

If present, always contains at least message and code . Other present fields depend on the command.

Command-specific JSON output

Here's an example success output for rover subgraph publish:

"json_version": "1",
"data": {
"api_schema_hash": "a1bc0d",
"supergraph_was_updated": true,
"subgraph_was_created": true,
"subgraph_was_updated": true,
"success": true
"error": null

And here's an example error output:

"json_version": "1",
"data": {
"api_schema_hash": null,
"subgraph_was_created": false,
"subgraph_was_updated": true,
"supergraph_was_updated": false,
"success": true
"error": {
"message": "Encountered 2 build errors while trying to build subgraph \"subgraph\" into supergraph \"name@current\".",
"code": "E029",
"details": {
"build_errors": [
"message": "[Accounts] -> Things went really wrong",
"code": "AN_ERROR_CODE",
"type": "composition",
"message": "[Films] -> Something else also went wrong",
"code": null,
"type": "composition"

This particular error object includes details about what went wrong. Notice that even though errors occurred while executing this command, data.success is still true. That's because the errors are build errors associated with composing the . Although failed, the publish itself succeeded.

Example jq script

You can combine the --format json flag with the jq command line tool to create powerful custom workflows. For example, this gist demonstrates converting output from rover {sub}graph check my-graph --format json to Markdown.

Writing to a file

The --output option enables you to specify a file destination for writing a Rover command's output:

rover supergraph compose --output ./supergraph-schema.graphql --config ./supergraph.yaml

If the specified file already exists, Rover overwrites it.

This functionality is available in Rover v0.11.0 and later. In earlier versions of Rover, the --output option instead provides the functionality that's now provided by the --format option.

Current versions of Rover still support using --output like --format, but that support is deprecated and will be removed in a future release.

Setting config storage location

Rover stores your configuration in a local file and uses it when making requests. By default, this file is stored in your operating system's default configuration directory, in a file named .sensitive.

You can override this file's location by setting the APOLLO_CONFIG_HOME environment variable. This can be useful for CI systems that don't give you access to default operating system directories.

# Stores config in ./myspecialconfig/rover.toml

Git context

Rover sends non-confidential information about your Git environment to GraphOS when you run a check or publish command. This information is displayed in relevant views of the Studio UI, making it easier to track down where schema changes were proposed or published:

Checks info in GraphOS Studio

This Git information includes:

  • The remote URL of your Git repository (stripped of any usernames/passwords)
  • The current commit's SHA
  • The committer of the current SHA
  • The current branch name

To see these values, run any check or publish command with the --log trace option.


None of this information should be sensitive, but if you want to override these values, you can set the following environment variables:


Non-Git version control

If you use a version control system besides Git, you can use the environment variables described in Git context to set similar information relevant to your VCS tool,

Currently, only Git is fully supported by .

Bypassing TLS/SSL validation

In some configurations (especially in internal networks), you might need Rover to communicate over encrypted channels (e.g., HTTPS) while avoiding strict digital certificate verifications that validate hostnames. You might even need to bypass digital certificate validation entirely.

This is not recommended and considered much less secure. However, for cases where it's necessary, you can use the following flags to configure how Rover validates HTTPS requests:

  • The --insecure-accept-invalid-hostnames flag disables hostname validation. If hostname verification is not used, any valid certificate for any site is trusted for use from any other. This introduces a significant vulnerability to person-in-the-middle attacks.

  • The --insecure-accept-invalid-certs flag disables certificate validation. If invalid certificates are trusted, any certificate for any site is trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

Increasing request timeouts

By default, Rover times out requests to the GraphOS Studio API and your graph endpoints after 30 seconds. If you're executing a command that might take longer than 30 seconds to process, you can increase this timeout with the --client-timeout option:

rover subgraph check my-graph --validation-period 1m --client-timeout=60

Supported environment variables

You can configure Rover's behavior by setting the environment variables listed below.

If present, an environment variable's value takes precedence over all other methods of configuring the associated behavior.

APOLLO_HOMEThe path to the parent directory of Rover's binary. The default value is your operating system's default home directory. Rover will install itself in a folder called .rover inside the directory specified.
APOLLO_CONFIG_HOMEThe path where Rover's configuration is stored. The default value is your operating system's default configuration directory.
APOLLO_KEYThe API key that Rover should use to authenticate with GraphOS Studio.
APOLLO_TELEMETRY_DISABLEDSet to true if you don't want Rover to collect anonymous usage data.
APOLLO_VCS_REMOTE_URLThe URL of your project's remote repository. See Git context.
APOLLO_VCS_BRANCHThe name of the version-controlled branch. See Git context.
APOLLO_VCS_COMMITThe long identifier (SHA in Git) of the commit. See Git context.
APOLLO_VCS_AUTHORThe name and email of a commit's author (e.g., Jane Doe <>). See Git context.
NO_EMOJISet to 1 if you don't want Rover to print emojis.
NO_COLORSet to 1 if you don't want Rover to print color.
Proxy Configuration
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy