/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),
  (7) initializing a new graph project or MCP server with rover init,
  (8) working with Apollo Connectors, contracts, persisted queries, or client operations,
  (9) managing API keys, plugins, templates, or graph artifacts.
license: MIT
compatibility: Node.js v18+, Linux/macOS/Windows
metadata:
  author: apollographql
  version: "1.2.0"
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

# OAuth login via browser (recommended for local dev)
rover auth login

# Or interactive API key entry
rover config auth

# Or set environment variable (recommended for CI/CD)
export APOLLO_KEY=your-api-key

Step 3: Verify Installation

rover --version
rover auth whoami    # OAuth identity
rover config whoami  # API key identity

Step 4: Initialize a Project (optional)

# Create a new federated graph project
rover init

# Create a project with MCP server
rover init --mcp

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 init` | Initialize a new federated graph project | New project setup, MCP server setup | | `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 | | `rover connector` | Work with Apollo Connectors (run, test, list) | Connector development | | `rover contract` | Manage contract variants (describe, preview, publish) | API surface filtering | | `rover persisted-queries` | Generate and publish persisted query manifests (alias: `pq`) | Security, performance | | `rover client check` | Validate client operations against a graph schema | Client-side CI | | `rover auth login` | Authenticate via OAuth browser flow | Local dev auth | | `rover api-key` | Create, list, delete, rename, rotate API keys | Key management | | `rover readme` | Fetch or publish graph variant READMEs | Graph documentation | | `rover template` | List and use project templates | Scaffolding |

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

# Intro