/rover

name: rover
description: >
  Guide for using Apollo Rover CLI to manage GraphQL schemas and federation. Use this skill when:
  (1) publishing or fetching subgraph/graph schemas,
  (2) composing supergraph schemas locally or via GraphOS,
  (3) running local supergraph development with rover dev,
  (4) validating schemas with check and lint commands,
  (5) configuring Rover authentication and environment,
  (6) exploring or searching a graph's schema for agent-driven discovery (rover schema describe / rover schema search).
license: MIT
compatibility: Node.js v18+, Linux/macOS/Windows
metadata:
  author: apollographql
  version: "1.1.2"
allowed-tools: Bash(rover:*) Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep

Apollo Rover CLI Guide

Rover is the official CLI for Apollo GraphOS. It helps you manage schemas, run composition locally, publish to GraphOS, and develop supergraphs on your local machine.

Quick Start

Step 1: Install

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

# npm (cross-platform)
npm install -g @apollo/rover

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

Step 2: Authenticate

# Interactive authentication (opens browser)
rover config auth

# Or set environment variable
export APOLLO_KEY=your-api-key

Step 3: Verify Installation

rover --version
rover config whoami

Explore a Graph's Schema (start here for schema questions)

To answer "what's in this graph?", find a field, or write a query against a GraphOS graph, **fetch the API schema and pipe it into `rover schema`** — this keeps the SDL out of your context and returns only what you need:

# What can I query? (compact overview)
rover graph fetch <graph@variant> | rover schema describe -

# Find a field by concept/keyword (returns the path from a root operation)
rover graph fetch <graph@variant> | rover schema search - "<keyword>"

# Zoom into one type or field
rover graph fetch <graph@variant> | rover schema describe - --coord <Type.field> --depth 1

Three rules that keep this correct:

• Use **`rover graph fetch`** (the API schema) — **not** `rover supergraph fetch` (that returns composition SDL with federation internals like `join__`/`link__`).
• **Pipe** it in — never run `rover graph fetch` alone and read the raw SDL (a large schema floods your context; that's exactly what `rover schema` avoids).
• The `schema` commands read **piped SDL, not a graph ref** — `rover schema describe <graph@variant>` fails; you must fetch first and pipe.

Full reference, ranking rules, and the save-once pattern: [Schema Exploration](#schema-exploration-for-agents) and [references/schema.md](references/schema.md).

Core Commands Overview

| Command | Description | Use Case | |---------|-------------|----------| | `rover subgraph publish` | Publish subgraph schema to GraphOS | CI/CD, schema updates | | `rover subgraph check` | Validate schema changes | PR checks, pre-deploy | | `rover subgraph fetch` | Download subgraph schema | Local development | | `rover supergraph compose` | Compose supergraph locally | Local testing | | `rover dev` | Local supergraph development | Development workflow | | `rover graph publish` | Publish monograph schema | Non-federated graphs | | `rover schema describe` | Explore a schema by coordinate; **takes SDL via stdin/file, not a graph ref** — pipe from `rover graph fetch` | Agent schema discovery | | `rover schema search` | Search a schema by keyword; **takes SDL via stdin/file, not a graph ref** — pipe from `rover graph fetch` | Agent schema discovery |

Graph Reference Format

Most commands require a graph reference in the format:

<GRAPH_ID>@<VARIANT>

Examples:

• `my-graph@production`
• `my-graph@staging`
• `my-graph@current` (default variant)

Set as environment variable:

export APOLLO_GRAPH_REF=my-graph@production

Subgraph Workflow

Publishing a Subgraph

# From schema file
rover subgraph publish my-graph@production \
  --name products \
  --schema ./schema.graphql \
  --routing-url https://products.example.com/graphql

# From running server (introspection)
rover subgraph publish my-graph@production \
  --name products \
  --schema <(rover subgraph introspect http://localhost:4001/graphql) \
  --routing-url https://products.example.com/graphql

Checking Schema Changes

# Check against production traffic
rover subgraph check my-graph@production \
  --name products \
  --schema ./schema.graphql

Fetching Schema

# Fetch from GraphOS
rover subgraph fetch my-graph@production --name products

# Introspect running server
rover subgraph introspect http://localhost:4001/graphql

Supergraph Composition

Local Composition

Create `supergraph.yaml`:

federation_version: =2.9.0
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./products/schema.graphql
  reviews:
    routing_url: http://localhost:4002/graphql
    schema:
      subgraph_url: http://localhost:4002/graphql

`federation_version` here is the **composition version** — it only needs to be ≥ each subgraph's `@link` floor, so subgraphs pinned to a lower version compose fine. If a subgraph server throws `UNKNOWN_FEDERATION_LINK_VERSION` at startup, that's a client-library lag, not a composition problem. See the apollo-federation skill's [Federation versions](../apollo-federation/references/composition.md#federation-versions-floor-vs-composition).

Compose:

rover supergraph compose --config supergraph.yaml > supergraph.graphql

Fetch Composed Supergraph

rover supergraph fetch my-graph@production

> This returns the **supergraph SDL** (federation directives + `join__`/`link__` internals) — use it for composition/router work. To **explore what you can query** or write an operation, use `rover graph fetch` (the API schema) instead — see [Explore a Graph's Schema](#explore-a-gr