Index of every page on this site: llms.txt
All skills
apollographql avatar

/rover

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/apollographql/skills/rover

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈178 tokens for metadata: the name and description. ≈3.3k when used: this file. ≈18k more on demand in 12 files.

Description uses 8.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈712 characters, or 8.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 and 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

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

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.

Local Development with rover dev

Start a local Router with automatic schema composition:

# 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

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

Schema Exploration (for Agents)

rover schema describe and rover schema search let an agent explore a schema without loading the full SDL into context — that is the entire point of these commands.

⚠️ Never read the raw SDL into context. Running rover graph fetch <ref> (or rover graph introspect <url>) on its own prints the entire schema — hundreds to tens of thousands of lines — straight into your context, which defeats the purpose of these commands. Always pipe fetch output into rover schema describe/search: the SDL flows through stdin and only the compact overview/results reach you. (Fetching to a file is fine when the user actually wants the SDL.)

These commands also take SDL on stdin or a file, NOT a graph ref — you can't pass graph@variant to them. Fetch first, then pipe:

❌ rover schema describe my-graph@current             # error: looks for a file named that
❌ rover graph fetch my-graph@current                 # dumps the full SDL into your context
✅ rover graph fetch my-graph@current | rover schema describe -

To explore a graph in GraphOS, fetch its schema and pipe it in. Use rover graph fetch (the API schema) for "what can I query?" exploration — it omits federation internals. Reach for rover supergraph fetch only when you need composition details (join__/link__ types, subgraph structure):

# Overview of a GraphOS graph
rover graph fetch my-graph@current | rover schema describe -

# Find fields by keyword (results include paths from root operations)
rover graph fetch my-graph@current | rover schema search - "playback"

# Zoom into a coordinate, expanding referenced types one level
rover graph fetch my-graph@current | rover schema describe - --coord <Type.field> --depth 1

Coordinate forms: --coord accepts a type (User), a field (User.posts), a field argument (Type.field(arg:)), or a directive (@deprecated) — omit it for the overview.

search vs describe: reach for rover schema search first when matching a concept or keyword and you don't yet know the field name — it finds nested fields and shows the path from a root operation. The describe overview lists only root fields, so search is how you locate fields buried deeper. Use describe for the overview or once you know the type/field coordinate.

This enables a closed-loop workflow — search → describe → write a query — with no MCP server setup. See Schema Exploration for the full command reference, ranking rules, and the save-once pattern for large schemas.

Running the generated operation: Rover does not execute queries — it only manages and inspects schemas. To actually run a generated query you need the graph's endpoint:

  • Single-subgraph graph: rover subgraph list <graph@variant> prints the Routing Url — send the query there with curl.
  • Multi-subgraph / federated: the client endpoint is the router URL (find it in GraphOS Studio), not the per-subgraph routing URLs.
  • Don't try to discover the endpoint via the GraphOS Platform API — Rover keeps the API key in its profile/keychain, not $APOLLO_KEY, so ad-hoc API calls will come back unauthenticated.

Reference Files

Detailed documentation for specific topics:

  • Init - rover init project initialization and MCP server setup
  • Subgraphs - fetch, publish, check, lint, introspect, delete
  • Graphs - monograph commands (non-federated)
  • Supergraphs - compose, fetch, config format
  • Dev - rover dev for local development
  • Schema Exploration - describe, search, agent schema discovery workflows
  • Connectors - rover connector run, test, list, analyze, generate
  • Contracts - contract variant describe, preview, publish
  • Persisted Queries - generate and publish persisted query manifests
  • Client Operations - validate client operations, extract GraphQL documents
  • Configuration - install, auth, env vars, profiles, OAuth login
  • Additional Commands - template, readme, api-key, plugin, license, graph-artifact, completion, explain, docs

Common Patterns

CI/CD Pipeline

# 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

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

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

Output Formats

# 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 auth login, 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
  • USE rover init to scaffold new graph projects instead of manual setup
  • NEVER commit APOLLO_KEY or APOLLO_CLIENT_SECRET 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
  • USE rover schema search / rover schema describe (piped from a fetch) to explore large schemas instead of loading the full SDL into context
  • NEVER fetch a full schema into context just to explore it — pipe rover graph fetch/introspect into rover schema describe/search (a bare fetch is only for when the user wants the SDL file itself)
  • USE rover client check to validate client operations before deploying client changes
  • USE rover persisted-queries publish to register operations for persisted query enforcement

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning24d5 checks · Risk SAFE
  • Gen Agent Trust Hub24d

    This skill provides a comprehensive guide for managing GraphQL schemas using the Apollo Rover CLI. While it includes commands for remote installation and schema ingestion, these are standard operations targeting official Apollo GraphQL infrastructure and follow security best practices.

  • Socket24d

    No alerts

  • Snyk24d

    Risk: LOW · No issues

  • Runlayer9mo

    6/6 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 82/100

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 weeks ago
What it can do
Runs commands
compatibility
Node.js v18+, Linux/macOS/Windows
metadata
{
  "author": "apollographql",
  "version": "1.2.0"
}
All 1 allowed tools
Bash(rover:*) Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
  • CLI
  • graphql
  • apollo
  • rover
  • federation
  • schema
  • supergraph
  • graphos
  • subgraph

README badge

README badge for apollographql/skills/rover

Manages GraphQL schemas and federation via the Apollo Rover CLI, including publishing subgraphs, composing supergraphs, and validating schemas with check and lint commands. Designed for local schema exploration via piped commands (rover schema describe/search) and GraphOS integration workflows, with built-in support for federated and monograph architectures.

Generated from the current SKILL.md.

Does Rover work with both federated and non-federated GraphQL graphs?
Yes. Use `rover subgraph` commands for federated graphs and `rover graph` commands for monographs (non-federated graphs). Both workflows are supported.
How do I explore a large GraphQL schema without loading the entire SDL into context?
Pipe `rover graph fetch` into `rover schema describe` or `rover schema search` — these commands read the schema via stdin and return only a compact overview or search results, keeping context manageable.
What's the difference between `rover graph fetch` and `rover supergraph fetch`?
`rover graph fetch` returns the API schema (what you can query), while `rover supergraph fetch` returns the composed supergraph SDL with federation internals like `join__` and `link__`. Use the former for schema exploration and the latter for composition/router work.
Can Rover execute GraphQL queries, or does it only manage schemas?
Rover only manages and inspects schemas. To run a generated query, you must send it to the graph's endpoint separately using curl or another HTTP client.
Does this skill require a GraphOS account, or can I use Rover offline?
Most Rover commands (publish, fetch, check) require authentication with a GraphOS API key. Local composition with `rover supergraph compose` and schema exploration of local files work offline.

Generated from the current SKILL.md. These answers refresh after source changes.