Agent skill

rover

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.

View SKILL.md on GitHub Repository
Stars 45
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/apollographql/skills/tree/main/skills/rover

Metadata

Additional technical details for this skill

author
apollographql
version
1.0.1

SKILL.md

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

bash
# 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

bash
# Interactive authentication (opens browser)
rover config auth

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

Step 3: Verify Installation

bash
rover --version
rover config whoami

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

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:

bash
export APOLLO_GRAPH_REF=my-graph@production

Subgraph Workflow

Publishing a Subgraph

bash
# 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

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

Fetching Schema

bash
# 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:

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

Compose:

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

Fetch Composed Supergraph

bash
rover supergraph fetch my-graph@production

Local Development with rover dev

Start a local Router with automatic schema composition:

bash
# Start with supergraph config
rover dev --supergraph-config supergraph.yaml

# Start with GraphOS variant as base
rover dev --graph-ref my-graph@staging --supergraph-config local.yaml

With MCP Integration

bash
# Start with MCP server enabled
rover dev --supergraph-config supergraph.yaml --mcp

Reference Files

Detailed documentation for specific topics:

  • Subgraphs - fetch, publish, check, lint, introspect, delete
  • Graphs - monograph commands (non-federated)
  • Supergraphs - compose, fetch, config format
  • Dev - rover dev for local development
  • Configuration - install, auth, env vars, profiles

Common Patterns

CI/CD Pipeline

bash
# 1. Check schema changes
rover subgraph check $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql

# 2. If check passes, publish
rover subgraph publish $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql \
  --routing-url $ROUTING_URL

Schema Linting

bash
# Lint against GraphOS rules
rover subgraph lint --name products ./schema.graphql

# Lint monograph
rover graph lint my-graph@production ./schema.graphql

Output Formats

bash
# JSON output for scripting
rover subgraph fetch my-graph@production --name products --format json

# Plain output (default)
rover subgraph fetch my-graph@production --name products --format plain

Ground Rules

  • ALWAYS authenticate before using GraphOS commands (rover config auth or APOLLO_KEY)
  • ALWAYS use the correct graph reference format: graph@variant
  • PREFER rover subgraph check before rover subgraph publish in CI/CD
  • USE rover dev for local supergraph development instead of running Router manually
  • NEVER commit APOLLO_KEY to version control; use environment variables
  • USE --format json when parsing output programmatically
  • SPECIFY federation_version explicitly in supergraph.yaml for reproducibility
  • USE rover subgraph introspect to extract schemas from running services

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

apollographql/skills

apollo-client

Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Apollo Client errors or performance issues.

45 3
Explore
apollographql/skills

apollo-connectors

Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors with @source and @connect directives. Use this skill when the user: (1) mentions "connectors", "Apollo Connectors", or "REST Connector", (2) wants to integrate a REST API into GraphQL, (3) references @source or @connect directives, (4) works with files containing "# Note to AI Friends: This is an Apollo Connectors schema".

45 3
Explore
apollographql/skills

apollo-server

Guide for building GraphQL servers with Apollo Server 5.x. Use this skill when: (1) setting up a new Apollo Server project, (2) writing resolvers or defining GraphQL schemas, (3) implementing authentication or authorization, (4) creating plugins or custom data sources, (5) troubleshooting Apollo Server errors or performance issues.

45 3
Explore
apollographql/skills

apollo-kotlin

Guide for building applications with Apollo Kotlin, the GraphQL client library for Android and Kotlin. Use this skill when: (1) setting up Apollo Kotlin in a Gradle project for Android, Kotlin/JVM, or KMP, (2) configuring schema download and codegen for GraphQL services, (3) configuring an `ApolloClient` with auth, interceptors, and caching, (4) writing queries, mutations, or subscriptions,

45 3
Explore
apollographql/skills

rust-best-practices

Guide for writing idiomatic Rust code based on Apollo GraphQL's best practices handbook. Use this skill when: (1) writing new Rust code or functions, (2) reviewing or refactoring existing Rust code, (3) deciding between borrowing vs cloning or ownership patterns, (4) implementing error handling with Result types, (5) optimizing Rust code for performance, (6) writing tests or documentation for Rust projects.

45 3
Explore
apollographql/skills

apollo-mcp-server

Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs. Use this skill when: (1) setting up or configuring Apollo MCP Server, (2) defining MCP tools from GraphQL operations, (3) using introspection tools (introspect, search, validate, execute), (4) troubleshooting MCP server connectivity or tool execution issues.

45 3
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results