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.

referencespersisted-queries.md

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

Rover Persisted Queries Commands

Commands for generating and publishing persisted query manifests to Apollo GraphOS. The rover persisted-queries command group is also available under the alias rover pq.

What Are Persisted Queries?

Persisted queries (also called registered operations) let clients send a pre-registered operation ID instead of the full query text. The router looks up the ID and executes only operations it recognizes.

Benefits:

  • Security - The router rejects unknown operations, preventing arbitrary queries
  • Performance - Smaller request payloads (a hash instead of a full query string)
  • Visibility - All operations in production are known and registered in GraphOS

persisted-queries generate

Generate a persisted query manifest from .graphql files in your project.

# Scan current directory for .graphql files
rover pq generate --include "src/**/*.graphql"

# Write manifest to a file
rover pq generate --include "src/**/*.graphql" --manifest-path ./pq-manifest.json

# Exclude generated files
rover pq generate \
  --include "src/**/*.graphql" \
  --exclude "src/__generated__/**"

# Scan a specific directory
rover pq generate --include "**/*.graphql" --root-dir ./my-app

# Preserve comments above operations in the manifest
rover pq generate --include "src/**/*.graphql" --preserve-comments

Options:

Option Description
--include <PATTERN> Glob patterns for files to include (repeatable)
--exclude <PATTERN> Glob patterns for files to exclude (repeatable)
--root-dir <DIR> Root directory to scan (default: current directory)
--manifest-path, -m <FILE> Write manifest to this file instead of stdout
--preserve-comments Keep comment blocks preceding operations in the manifest body

Manifest format (Apollo):

{
  "format": "apollo-persisted-query-manifest",
  "version": 1,
  "operations": [
    {
      "id": "sha256-hash-of-the-operation-body",
      "body": "query GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n  }\n}",
      "name": "GetUser",
      "type": "query"
    }
  ]
}

All operations must be named. Anonymous operations cause an error.

persisted-queries publish

Publish a persisted query manifest to a graph in Apollo GraphOS.

# Publish using a graph ref (list must be linked to the variant)
rover pq publish my-graph@production \
  --manifest ./pq-manifest.json

# Publish using explicit graph ID and list ID
rover pq publish \
  --graph-id my-graph \
  --list-id my-list-id \
  --manifest ./pq-manifest.json

# Publish a Relay-format manifest
rover pq publish my-graph@production \
  --manifest ./relay-manifest.json \
  --manifest-format relay

# Override the client name for all operations
rover pq publish my-graph@production \
  --manifest ./pq-manifest.json \
  --for-client-name my-web-app

# Read manifest from stdin
cat pq-manifest.json | rover pq publish my-graph@production --manifest -

Options:

Option Description
<GRAPH_REF> Graph reference with a linked persisted query list
--graph-id <ID> Graph ID (use with --list-id instead of a graph ref)
--list-id <ID> Persisted query list ID (use with --graph-id)
--manifest <PATH> Path to the manifest file, or - for stdin (required)
--manifest-format <FORMAT> Manifest format: apollo (default) or relay
--for-client-name <NAME> Override the clientName field in all operations

Identifying the target list:

  • Pass a <GRAPH_REF> if a persisted query list is linked to that variant.
  • Pass --graph-id and --list-id together to target a specific list directly.
  • You cannot combine a graph ref with --graph-id or --list-id.

CI/CD Workflow

A typical pipeline generates the manifest from client source files and publishes it before deploying:

# 1. Generate the manifest
rover pq generate \
  --include "src/**/*.graphql" \
  --manifest-path ./pq-manifest.json

# 2. Publish to GraphOS
rover pq publish $APOLLO_GRAPH_REF \
  --manifest ./pq-manifest.json

GitHub Actions Example

steps:
  - name: Generate persisted query manifest
    run: |
      rover pq generate \
        --include "src/**/*.graphql" \
        --manifest-path ./pq-manifest.json

  - name: Publish persisted queries
    run: |
      rover pq publish $APOLLO_GRAPH_REF \
        --manifest ./pq-manifest.json
    env:
      APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
      APOLLO_GRAPH_REF: my-graph@production

Working with Relay

If your client uses Relay, generate the manifest using Relay's compiler, then publish it with the --manifest-format relay flag:

rover pq publish my-graph@production \
  --manifest ./relay-persisted-queries.json \
  --manifest-format relay

Use --for-client-name to tag operations with the client name (Relay manifests do not include one by default):

rover pq publish my-graph@production \
  --manifest ./relay-persisted-queries.json \
  --manifest-format relay \
  --for-client-name my-relay-app

Extracting Operations from Source Files

If your operations are embedded in TypeScript/JavaScript source files (for example, as gql tagged template literals), extract them first with rover client extract:

# Extract .graphql files from source
rover client extract --include "src/**/*.{ts,tsx}" --out-dir ./graphql

# Generate manifest from the extracted files
rover pq generate --include "graphql/**/*.graphql" --manifest-path ./pq-manifest.json

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.