@apollo/rover

What is @apollo/rover?

@apollo/rover is a command-line tool for managing and interacting with Apollo Federation. It allows you to work with your GraphQL schemas, manage subgraphs, and interact with Apollo Studio.

What are @apollo/rover's main functionalities?

Fetching a GraphQL Schema

Fetches the latest version of a GraphQL schema from Apollo Studio for a specific graph.

rover graph fetch my-graph@current

Publishing a Subgraph

Publishes a subgraph schema to Apollo Studio, allowing it to be composed into a federated graph.

rover subgraph publish my-graph@current --name products --schema ./schema.graphql --routing-url http://localhost:4001

Composing a Supergraph

Composes a supergraph schema from multiple subgraph schemas using a configuration file.

rover supergraph compose --config ./supergraph-config.yaml

Checking Schema Changes

Checks a local schema against the current schema in Apollo Studio to ensure compatibility and detect breaking changes.

rover graph check my-graph@current --schema ./schema.graphql

Other packages similar to @apollo/rover

graphql-cli

graphql-cli is a command-line tool that provides various utilities for working with GraphQL schemas and servers. It offers functionalities like schema validation, introspection, and code generation. Compared to @apollo/rover, graphql-cli is more general-purpose and not specifically tailored for Apollo Federation.

graphql-inspector

graphql-inspector is a tool for validating, diffing, and merging GraphQL schemas. It helps in detecting changes, breaking changes, and validating schemas against operations. While it offers some overlapping features with @apollo/rover, it is more focused on schema inspection and validation rather than managing federated graphs.

apollo

The apollo npm package provides a set of tools for building and managing GraphQL services with Apollo Server and Apollo Client. It includes functionalities for schema stitching, schema validation, and more. While it shares some functionalities with @apollo/rover, it is more comprehensive and not limited to command-line operations.

README

Rover

This is the home of Rover, the new CLI for Apollo's suite of GraphQL developer productivity tools.

Note

This README contains just enough info to get you started with Rover. Our docs contain more detailed information that should be your primary reference for all things Rover.

Usage

A few useful Rover commands to interact with your graphs:

1. Fetch a graph from a federated remote endpoint.

rover graph fetch test@cats

1. Validate recent changes made to your local graph with rover graph check.

rover graph check --schema=./path-to-valid-sdl test@cats

1. Publish your local graph to Apollo Studio.

rover graph publish --schema ./path-to-valid-schema test@cats

Command-line options

Rover - Your Graph Companion

Usage: rover [OPTIONS] <COMMAND>

Commands:
  cloud
          Cloud configuration commands
  config
          Configuration profile commands
  contract
          Contract configuration commands
  dev
          Combine multiple subgraphs into a local supergraph
  supergraph
          Supergraph schema commands
  graph
          Graph API schema commands
  template
          Commands for working with templates
  readme
          Readme commands
  subgraph
          Subgraph schema commands
  docs
          Interact with Rover's documentation
  update
          Commands related to updating rover
  persisted-queries
          Commands for persisted queries [aliases: pq]
  explain
          Explain error codes
  license
          Commands for fetching offline licenses
  help
          Print this message or the help of the given subcommand(s)

Options:
  -l, --log <LOG_LEVEL>
          Specify Rover's log level

      --format <FORMAT_KIND>
          Specify Rover's format type

          [default: plain]
          [possible values: plain, json]

  -o, --output <OUTPUT_FILE>
          Specify a file to write Rover's output to

      --insecure-accept-invalid-certs
          Accept invalid certificates when performing HTTPS requests.

          You should think very carefully before using this flag.

          If invalid certificates are trusted, any certificate for any site will be trusted for use. This includes expired certificates. This introduces significant vulnerabilities, and should only be used as a last resort.

      --insecure-accept-invalid-hostnames
          Accept invalid hostnames when performing HTTPS requests.

          You should think very carefully before using this flag.

          If hostname verification is not used, any valid certificate for any site will be trusted for use from any other. This introduces a significant vulnerability to man-in-the-middle attacks.

      --client-timeout <CLIENT_TIMEOUT>
          Configure the timeout length (in seconds) when performing HTTP(S) requests

          [default: 30]

      --skip-update-check
          Skip checking for newer versions of rover

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Read the getting started guide by running:

    $ rover docs open start

To begin working with Rover and to authenticate with Apollo Studio,
run the following command:

    $ rover config auth

This will prompt you for an API Key that can be generated in Apollo Studio.

The most common commands from there are:

    - rover graph fetch: Fetch a graph schema from the Apollo graph registry
    - rover graph check: Check for breaking changes in a local graph schema against a graph schema in the Apollo graph
registry
    - rover graph publish: Publish an updated graph schema to the Apollo graph registry

You can open the full documentation for Rover by running:

    $ rover docs open

This repo is organized as a cargo workspace, containing several related projects:

• rover: Apollo's suite of GraphQL developer productivity tools
• houston: utilities for configuring Rover
• robot-panic: a fork of rust-cli/human-panic adjusted for Rover
• rover-client: an HTTP client for making GraphQL requests for Rover
• sputnik: a crate to aid in collection of anonymous data for Rust CLIs
• timber: Rover's logging formatter

Installation Methods

Linux and MacOS curl | sh installer

To install the latest release of Rover:

curl -sSL https://rover.apollo.dev/nix/latest | sh

To install a specific version of Rover (note the v prefixing the version number):

Note: If you're installing Rover in a CI environment, it's best to target a specific version rather than using the latest URL, since future major breaking changes could affect CI workflows otherwise.

curl -sSL https://rover.apollo.dev/nix/v0.10.0 | sh

You will need curl installed on your system to run the above installation commands. You can get the latest version from the curl downloads page.

Note: rover supergraph compose is currently not available for Alpine Linux. You may track the progress for supporting this command on Alpine in this issue.

Windows PowerShell installer

iwr 'https://rover.apollo.dev/win/latest' | iex

To install a specific version of Rover (note the v prefixing the version number):

Note: If you're installing Rover in a CI environment, it's best to target a specific version rather than using the latest URL, since future major breaking changes could affect CI workflows otherwise.

iwr 'https://rover.apollo.dev/win/v0.10.0' | iex

npm installer

Rover is distributed on npm for easy integration with your JavaScript projects.

devDependency install

If you'd like to install rover as a devDependency in your JavaScript project, you can run npm i --save-dev @apollo/rover. You can then call rover directly in your package.json scripts, or you can run npx rover in your project directory to execute commands.

Manual download and install

If you'd like to call rover from any directory on your machine, you can run npm i -g @apollo/rover.

Note: Unfortunately if you've installed npm without a version manager such as nvm, you may have trouble with global installs. If you encounter an EACCES permission-related error while trying to install globally, DO NOT run the install command with sudo. This support page has information that should help to resolve this issue.

Without curl

You can also download the binary for your operating system and manually add its location to your PATH.

Unsupported architectures

If you don't see your CPU architecture supported as part of our release pipeline, you can build from source with cargo. Clone this repo, and run cargo xtask dist --version v0.1.3. This will compile a released version of Rover for you, and place the binary in your target directory.

git clone https://github.com/apollographql/rover
cargo xtask dist --version v0.1.3

From here you can either place the binary in your PATH manually, or run ./target/release/{optional_target}/rover install.

Contributions

See this page for info about contributing to Rover.

Licensing

Source code in this repository is covered by (i) an MIT compatible license or (ii) the Elastic License 2.0, in each case, as designated by a licensing file within a subdirectory or file header. The default throughout the repository is an MIT compatible license, unless a file header or a licensing file in a subdirectory specifies another license.