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
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/rover
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
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
📊 Stats
Stars98
Forks11
LanguageShell
LicenseMIT
📦 Ships with apollo-skills
</> SKILL.md
rover.SKILL.md
---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.1"
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
```bash
# macOS/Linux
curl -sSL https://rover.apollo.dev/nix/latest | sh
# npm (cross-platform)
npm install -g @apollo/rover
## 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:
- 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).
| `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:
> 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-graphs-schema-start-here-for-schema-questions).
## 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
```
## 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:
>
> ```bash
> ❌ 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
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):
**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](references/schema.md) 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; for a GraphOS cloud router, `rover cloud config fetch <graph@variant>`), 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.
- 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
- 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)
