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.

referencescontracts.md

≈1.6k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Rover Contract Commands

Commands for managing contract variants in Apollo GraphOS. Contracts create filtered views of a supergraph schema, exposing different API surfaces to different consumers.

What Are Contracts?

A contract variant applies tag-based filters to a source variant's supergraph schema. Subgraph authors annotate types and fields with @tag(name: "...") directives, and the contract's include/exclude lists determine which tagged elements appear in the filtered schema. This lets you serve tailored APIs (public vs. internal, partner vs. mobile) from a single supergraph.

contract describe

View the current configuration of a contract variant.

rover contract describe my-graph@public-api

Output includes:

  • Source variant name
  • Include tags
  • Exclude tags
  • Whether unreachable types are hidden

Options:

Option Description
<GRAPH_REF> The contract variant to describe (required)

contract publish

Publish an updated contract configuration to GraphOS and trigger a launch.

# Include only fields tagged "public", exclude "internal", hide unreachable types
rover contract publish my-graph@public-api \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types

# Multiple include tags
rover contract publish my-graph@partner-api \
  --include-tag public \
  --include-tag partner \
  --no-exclude-tags \
  --hide-unreachable-types

# Exclude specific tags, include everything else
rover contract publish my-graph@external-api \
  --no-include-tags \
  --exclude-tag internal \
  --exclude-tag experimental \
  --hide-unreachable-types

# Set the source variant (required on first publish)
rover contract publish my-graph@public-api \
  --source-variant production \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types

# Publish without triggering a launch
rover contract publish my-graph@public-api \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types \
  --no-launch

Options:

Option Description
<GRAPH_REF> The contract variant to publish to (required)
--source-variant <NAME> Source variant for this contract (required on first publish, cannot be changed later)
--include-tag <TAG> Tag names to include (repeatable)
--no-include-tags Use an empty include list (mutually exclusive with --include-tag)
--exclude-tag <TAG> Tag names to exclude (repeatable)
--no-exclude-tags Use an empty exclude list (mutually exclusive with --exclude-tag)
--hide-unreachable-types Hide types that are unreachable from any root operation
--no-hide-unreachable-types Keep unreachable types in the contract schema
--no-launch Do not trigger a launch after publishing

Every publish requires exactly one flag from each pair: --include-tag or --no-include-tags, --exclude-tag or --no-exclude-tags, and --hide-unreachable-types or --no-hide-unreachable-types.

contract preview

Preview the contract schema a filter configuration would produce, without publishing it. The build runs asynchronously on GraphOS. By default, Rover polls until it completes.

# Preview a filter configuration
rover contract preview my-graph@production \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types

# Start the build and return immediately
rover contract preview my-graph@production \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types \
  --async

# Check the status of a previously started build
rover contract preview my-graph@production \
  --build-id abc123

Options:

Option Description
<GRAPH_REF> The variant whose supergraph to filter (required)
--include-tag <TAG> Tag names to include (repeatable)
--no-include-tags Use an empty include list
--exclude-tag <TAG> Tag names to exclude (repeatable)
--no-exclude-tags Use an empty exclude list
--hide-unreachable-types Hide unreachable types
--no-hide-unreachable-types Keep unreachable types
--async Return immediately with a build ID instead of polling
--build-id <ID> Check the status of a previous build (conflicts with all filter flags)

When not using --build-id, filter flags follow the same pairing rules as contract publish.

Workflow Examples

Setting Up a Public API Contract

# 1. Tag subgraph fields in your schemas with @tag(name: "public")
# 2. Publish the contract configuration
rover contract publish my-graph@public-api \
  --source-variant production \
  --include-tag public \
  --no-exclude-tags \
  --hide-unreachable-types

# 3. Verify the result
rover contract describe my-graph@public-api

Previewing Before Publishing

# Test a new filter configuration without affecting the live contract
rover contract preview my-graph@production \
  --include-tag public \
  --include-tag partner \
  --no-exclude-tags \
  --hide-unreachable-types

# If the preview looks good, publish
rover contract publish my-graph@partner-api \
  --source-variant production \
  --include-tag public \
  --include-tag partner \
  --no-exclude-tags \
  --hide-unreachable-types

Updating Contract Filters

# Add a new tag to the existing contract
rover contract publish my-graph@public-api \
  --include-tag public \
  --include-tag beta \
  --no-exclude-tags \
  --hide-unreachable-types

Common Errors

E039 - Not a contract variant: The specified variant is not a contract variant. Verify the graph@variant is correct and that the variant is configured as a contract in GraphOS Studio.

E040 - Contract publish failed: The contract configuration could not be published. Check the error message for details on invalid inputs.

When to Use Contracts

  • Public vs. internal APIs: Expose a subset of your supergraph to external consumers.
  • Partner-specific APIs: Give each partner access to only the fields they need.
  • Platform APIs: Serve different schemas to mobile, web, or IoT clients.
  • Staged rollouts: Preview contract changes with contract preview before publishing.

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.