Terminal
Terminal/Skill
Guide for the Rover CLI to publish and fetch schemas, compose supergraphs, run rover dev, and run check and lint.
By Apollo GraphQL
Works with
npx skills add apollographql/skills --skill roverRover 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.
# 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
# Interactive authentication (opens browser)
rover config auth
# Or set environment variable
export APOLLO_KEY=your-api-key
rover --version
rover config whoami
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:
rover graph fetch (the API schema) — not rover supergraph fetch (that returns composition SDL with federation internals like join__/link__).rover graph fetch alone and read the raw SDL (a large schema floods your context; that's exactly what rover schema avoids).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.
| 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 |
Most commands require a graph reference in the format:
<GRAPH_ID>@<VARIANT>
Examples:
my-graph@productionmy-graph@stagingmy-graph@current (default variant)Set as environment variable:
export APOLLO_GRAPH_REF=my-graph@production
# 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
# Check against production traffic
rover subgraph check my-graph@production \
--name products \
--schema ./schema.graphql
# Fetch from GraphOS
rover subgraph fetch my-graph@production --name products
# Introspect running server
rover subgraph introspect http://localhost:4001/graphql
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
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, userover graph fetch(the API schema) instead — see Explore a Graph's Schema.
rover devStart 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
# Start with MCP server enabled
rover dev --supergraph-config supergraph.yaml --mcp
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>(orrover 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 intorover 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@variantto 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:
rover subgraph list <graph@variant> prints the Routing Url — send the query there with curl.rover cloud config fetch <graph@variant>), not the per-subgraph routing URLs.$APOLLO_KEY, so ad-hoc API calls will come back unauthenticated.Detailed documentation for specific topics:
# 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
# Lint against GraphOS rules
rover subgraph lint --name products ./schema.graphql
# Lint monograph
rover graph lint my-graph@production ./schema.graphql
# 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
rover config auth or APOLLO_KEY)graph@variantrover subgraph check before rover subgraph publish in CI/CDrover dev for local supergraph development instead of running Router manuallyAPOLLO_KEY to version control; use environment variables--format json when parsing output programmaticallyfederation_version explicitly in supergraph.yaml for reproducibilityrover subgraph introspect to extract schemas from running servicesrover schema search / rover schema describe (piped from a fetch) to explore large schemas instead of loading the full SDL into contextrover graph fetch/introspect into rover schema describe/search (a bare fetch is only for when the user wants the SDL file itself)