Launch Apollo Studio

Migrating from the Apollo CLI


The Apollo CLI is Apollo's previous CLI tool for managing graphs with Apollo Studio's graph registry.

This guide helps you migrate to Rover from the Apollo CLI by highlighting key differences between the tools and providing examples that use Rover to perform common Apollo CLI workflows.

Prerequisites

We recommend reading Rover conventions first, because this guide builds off of it.

It's also helpful to install and configure Rover before reading through this guide.

Configuring

Rover's approach to configuration is much more explicit and less abstracted than the Apollo CLI. Most configuration options in Rover are specified as flags on a particular command, rather than in a config file.

The only config files that Rover uses are hidden config files created by the config auth command, along with a YAML file that's specifically for the supergraph compose command.

Authenticating with Studio

The Apollo CLI authenticates with Apollo Studio by reading an environment variable to determine the API key to use. With Rover, the recommended way to set API keys is with the config auth command. This command is interactive, however, so you can still use an environment variable in your CI/CD environment.

If you aren't sure where your API key is being read from or you're experiencing issues with your key, you can use the config whoami command to debug.

Replacing apollo.config.js

The Apollo CLI reads an apollo.config.js file to load certain configuration options. The following table lists the most common fields in apollo.config.js and how they translate to options in Rover (also see an example):

apollo.config.js Field Rover Option
name/service.name

GRAPH_REF positional argument. This is the first positional argument in any command that uses the Apollo graph registry.

service.localSchemaFile

--schema flag.

Note: This flag doesn't support multiple files.

service.endpoint.url

URL positional argument. This is the first positional argument to introspect commands.

service.endpoint.headers

--header/-H flag in introspect commands

Note: Use this flag multiple times to specify multiple headers.

Introspection

In the Apollo CLI, introspection of running services happens behind the scenes when you pass an --endpoint option to commands like service:push, service:check, and service:download. In Rover, you instead run the graph introspect command and pipe its result to the similar graph/subgraph push and graph/subgraph check commands.

This separation of steps makes Rover's use of introspection more flexible and transparent. In addition, separating introspection into its own step makes it more debuggable if you run into errors.

If your goal is to download a schema from a running endpoint, you can output the result of graph introspect directly to a file. Find more about how stdin/stdout works with Rover here.

Monolithic vs. federated graphs

The Apollo CLI's API uses the apollo service:* command set for working with both monolithic and federated graphs. Rover treats graphs and federated graphs separately.

When working with federated graphs in Rover, you typically use the subgraph command set, because most operations on a federated graph interact with one of its subgraphs (e.g., checking changes to a single subgraph). Rover also provides a supergraph command set, which is used for composing and working with supergraph schemas.

For more information on the differences between graphs, subgraphs, and supergraphs, see Conventions.

Limitations of Rover

For the sake of maintainability, roadmap considerations, and time, Rover intentionally lacks certain features of the Apollo CLI. Some of these features might be added at a later date, but there is no timeline for their release.

Client commands

Rover's focus is around providing an excellent graph management experience. For that reason, we have intentionally omitted commands that focus on client project development, such as client:codegen and client:check.

Globs

The Apollo CLI uses globs extensively to support using multiple local files, and even automatic discovery of files in a directory tree. While this was helpful in certain cases, the globbing strategy in the Apollo CLI caused many issues. Rover intentionally leaves globs off of file specifiers for initial release.

As a workaround, you might be able to use cat to combine multiple files and pass them to Rover with stdin. See this example.

Machine-readable output

In the Apollo CLI, many commands support alternate output formatting options, such as --json and --markdown. Currently, Rover only supports --output json, and leaves markdown formatting up to the consumer. For more information on JSON output in Rover, see these docs.

An example script for converting output from rover {sub}graph check my-graph --output json can be found in this gist.

Examples

Note: these examples assume an environment variable or config file has been set up to authenticate the Apollo CLI, and the rover config auth command has been run to authenticate Rover.

Fetching a graph's schema from Apollo's graph registry

## Apollo CLI ##
# automatically outputs to schema.graphql
apollo client:download-schema --graph my-graph --variant prod

## Rover ##
# automatically outputs to stdout. Can redirect to schema.graphql
rover graph fetch my-graph@prod > schema.graphql

Fetching a graph's schema from introspection

## Apollo CLI ##
# automatically outputs to schema.graphql
# can ONLY output introspection results in JSON
apollo service:download --endpoint http://localhost:4000

## Rover ##
# automatically outputs to stdout. Can redirect to schema.graphql
# can ONLY output SDL
rover graph introspect http://localhost:4000

Publishing a monolithic schema to the Apollo graph registry

## Apollo CLI ##
apollo service:push --graph my-graph --variant prod --endpoint http://localhost:4000

## Rover ##
rover graph introspect http://localhost:4000 | rover graph publish my-graph@prod --schema -

Checking monolithic graph changes

## Apollo CLI ##
apollo service:check --graph my-graph --variant prod --localSchemaFile ./schema.graphql

## Rover ##
rover graph publish my-graph@prod --schema ./schema.graphql

Publishing a federated subgraph

Subgraphs were previously referred to as "implementing services" or just "services" (an overloaded term) in the Apollo CLI.

## Apollo CLI ##
apollo service:push \
  --graph my-graph \
  --variant prod \
  --serviceName users \
  --localSchemaFile ./users.graphql

## Rover ##
rover subgraph publish my-graph@prod \
  --schema ./users.graphql \
  --name users

Checking a subgraph's changes

## Apollo CLI ##
apollo service:check \
  --graph my-graph \
  --variant prod \
  --serviceName users \
  --localSchemaFile ./users.graphql

## Rover ##
rover subgraph check my-graph@prod \
  --schema ./users.graphql \
  --name users

Checking a graph's changes (with a config file)

The config file in the Apollo CLI was meant to act as a substitute for the flags in the command usage itself, but often this left the details of what commands were being run too abstract and difficult to follow. Rover's more verbose usage aims to be more plain and explicit.

// apollo.config.js
module.exports = {
    // this is the GRAPH_REF positional arg in Rover
    name: 'my-graph@prod',
    endpoint: {
      url: 'http://localhost:4001',
      headers: {
        // passed with the --header flag in Rover
        authorization: 'Bearer wxyz',
      },
    },
};
## Apollo CLI ##
apollo service:check

## Rover ##
# (no config file needed)
rover graph introspect http://localhost:4001 --header "authorization: Bearer wxyz" \
| rover graph check my-graph@prod --schema -

Pushing Subgraph Changes (with a config file)

// apollo.config.js
module.exports = {
    service: {
      // this is the GRAPH_REF positional arg in Rover
      name: 'my-graph@prod',
      // multiple schema files that can be concatenated
      localSchemaFile: './*.graphql'
    }
};
## Apollo CLI ##
apollo service:push --serviceName users

## Rover ##
# (no config file needed)
# globs don't work natively with Rover, so you can use a command like `awk 1`
# to combine multiple files on *nix machines
awk 1 *.graphql | rover subgraph publish my-graph@prod --name users --schema -
Edit on GitHub