/rover

Rover Schema Commands

Commands for exploring a GraphQL schema: get a structured overview, zoom into a single type or field, or search for types and fields by keyword. These are designed for agent-driven schema discovery — an agent can search → describe → write a query in a closed loop, without loading a huge SDL into its context.

Local and offline — these take SDL, not a graph ref. rover schema describe and rover schema search read SDL from a file or from stdin only; they do not call GraphOS and need no authentication. Unlike other rover commands, passing a graph ref fails:

❌ rover schema describe my-graph@current
✅ rover graph fetch my-graph@current | rover schema describe -

Pipe — don't read the raw SDL. Running rover graph fetch/introspect on its own dumps the whole schema into context; always pipe it into describe/search so only the compact result reaches you. To explore a graph that lives in GraphOS, fetch its schema first and pipe it in — see GraphOS Schema Exploration.

schema describe

Describe a schema by type, field, or directive. With no coordinate it prints a schema overview; with --coord it zooms into a single element.

# Schema overview (type counts, root operations)
rover schema describe schema.graphql

# Describe one type
rover schema describe schema.graphql --coord User

# Describe one field
rover schema describe schema.graphql --coord User.posts

# Expand referenced types one level deep
rover schema describe schema.graphql --coord User --depth 1

# Describe a directive
rover schema describe schema.graphql --coord @deprecated

# Raw SDL excerpt for the coordinate instead of a description
rover schema describe schema.graphql --coord User --view sdl

# Read from stdin (omit the file or pass -)
cat schema.graphql | rover schema describe
cat schema.graphql | rover schema describe - --coord User

# Machine-readable output
rover schema describe schema.graphql --coord User --format json

Coordinate forms (apollo-compiler SchemaCoordinate syntax):

Options:

Field coordinates automatically include the field's argument and return types, so a single --coord Type.field call gives an agent enough context to use it.

schema search

Find types and fields by keyword. Each result is a schema coordinate plus the path(s) from a root operation that reach it — enough to write a query from a single search.

# Single keyword
rover schema search schema.graphql email

# Multiple terms — all must match (AND)
rover schema search schema.graphql "create post"

# Comma-separated clauses — any clause matches (OR)
rover schema search schema.graphql "email, displayName"

# Limit results (default 10)
rover schema search schema.graphql author --limit 20

# Include deprecated members
rover schema search schema.graphql id --include-deprecated

# Read from stdin (FILE must be -)
cat schema.graphql | rover schema search - user

# Machine-readable output
rover --format json schema search schema.graphql email

Example output:

1 result for "email"

User.email — The user's email address
  field  ·  via Query.user, Mutation.createPost -> Post.author

The via line lists complete paths from a Query/Mutation root to the match, with intermediate types included — so an agent can turn a result straight into an operation.

Ranking — results are ordered by match tier (strongest first), then alphabetically by coordinate. Names are split on camelCase / snake_case and matching is case-insensitive:

Options:

GraphOS Schema Exploration

schema describe and schema search work on local SDL, so to explore a graph registered in GraphOS you fetch its schema first and pipe it in. Any rover ... fetch command prints SDL to stdout in its default (plain) format, so it pipes directly.

Authentication: the fetch step calls GraphOS and needs auth (rover config auth or APOLLO_KEY) and a graph reference (graph@variant). The schema describe / schema search step is local and needs neither.

Fetch sources:

Pipe directly (no temp file):

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

# Find fields by keyword
rover graph fetch my-graph@current | rover schema search - "playback"

# Zoom into a coordinate from the search results
rover graph fetch my-graph@current | rover schema describe - --coord <Type.field> --depth 1

Save once, explore repeatedly (more efficient for large schemas):

rover supergraph fetch my-graph@current > schema.graphql
rover schema search   schema.graphql "playback"
rover schema describe schema.graphql --coord <Type.field> --depth 1

A local running server works too, via introspection:

rover subgraph introspect http://localhost:4001/graphql | rover schema search - "user"

Closed-Loop Agent Workflow

With these two commands an agent can go from a vague request to an executable query with no human guidance:

# 1. What's in this graph?
rover graph fetch mcp-showcase-spotify@current | rover schema describe

# 2. Find the relevant fields — returns Player.currentlyPlaying
#    via Query.me -> CurrentUser.player
rover graph fetch mcp-showcase-spotify@current | rover schema search - "currently playing"

# 3. Expand the type on the returned path
rover graph fetch mcp-showcase-spotify@current | rover schema describe - --coord Player.currentlyPlaying --depth 1

# 4. Write and run the query using the `via` path from step 2.

When piping, prefer the save-once pattern in step 2–3 if you run several searches against the same graph — it avoids re-fetching.

Running it (step 4): Rover does not execute operations. Get the endpoint — rover subgraph list <graph@variant> shows the Routing Url for a single-subgraph graph, or use the router URL from GraphOS Studio (for a cloud router, rover cloud config fetch <graph@variant>) for a federated one — then send the query with curl. Don't hunt for it via the Platform API; the API key lives in Rover's profile/keychain, not $APOLLO_KEY.

Tips

• search vs describe: use search to find a field by concept/keyword — it surfaces nested fields with their path from a root operation. Use describe for the overview or a known coordinate. The overview lists only root fields, so search is how you locate nested ones (e.g. search "service provider" → Launch.launchServiceProvider, which no overview shows).
• These commands are offline; only the fetch/introspect step needs network and auth.
• Use --coord Type.field --depth 1 to pull a field plus its argument and return types in one call.
• Use rover --format json schema search ... (or describe) when a script or tool consumes the output.
• For natural-language / semantic search (vector-based), see the apollo-mcp-server skill — rover schema search is keyword/fuzzy (lexical) matching.