Guide CLI Apollo Rover

Rover est le CLI officiel pour Apollo GraphOS. Il vous aide à gérer les schémas, exécuter la composition localement, publier vers GraphOS et développer des supergraphs sur votre machine locale.

Démarrage rapide

Étape 1 : Installation

# macOS/Linux
curl -sSL https://rover.apollo.dev/nix/latest | sh

# npm (multiplateforme)
npm install -g @apollo/rover

# Windows PowerShell
iwr 'https://rover.apollo.dev/win/latest' | iex

Étape 2 : Authentification

# Authentification interactive (ouvre le navigateur)
rover config auth

# Ou définir une variable d'environnement
export APOLLO_KEY=your-api-key

Étape 3 : Vérifier l'installation

rover --version
rover config whoami

Aperçu des commandes principales

Format de référence de graphe

La plupart des commandes nécessitent une référence de graphe au format :

<GRAPH_ID>@<VARIANT>

Exemples :

• my-graph@production
• my-graph@staging
• my-graph@current (variante par défaut)

Défini comme variable d'environnement :

export APOLLO_GRAPH_REF=my-graph@production

Flux de travail Subgraph

Publication d'un subgraph

# À partir d'un fichier de schéma
rover subgraph publish my-graph@production \
  --name products \
  --schema ./schema.graphql \
  --routing-url https://products.example.com/graphql

# À partir d'un serveur en cours d'exécution (introspection)
rover subgraph publish my-graph@production \
  --name products \
  --schema <(rover subgraph introspect http://localhost:4001/graphql) \
  --routing-url https://products.example.com/graphql

Vérification des modifications de schéma

# Vérifier par rapport au trafic de production
rover subgraph check my-graph@production \
  --name products \
  --schema ./schema.graphql

Récupération du schéma

# Récupérer depuis GraphOS
rover subgraph fetch my-graph@production --name products

# Faire l'introspection du serveur en cours d'exécution
rover subgraph introspect http://localhost:4001/graphql

Composition de supergraph

Composition locale

Créer 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

Composer :

rover supergraph compose --config supergraph.yaml > supergraph.graphql

Récupérer le supergraph composé

rover supergraph fetch my-graph@production

Développement local avec rover dev

Démarrer un Router local avec composition automatique de schéma :

# Démarrer avec la configuration du supergraph
rover dev --supergraph-config supergraph.yaml

# Démarrer avec la variante GraphOS comme base
rover dev --graph-ref my-graph@staging --supergraph-config local.yaml

Avec intégration MCP

# Démarrer avec le serveur MCP activé
rover dev --supergraph-config supergraph.yaml --mcp

Fichiers de référence

Documentation détaillée pour des sujets spécifiques :

• Subgraphs - fetch, publish, check, lint, introspect, delete
• Graphs - commandes monograph (non fédérés)
• Supergraphs - compose, fetch, format de configuration
• Dev - rover dev pour le développement local
• Configuration - installation, authentification, variables d'environnement, profils

Modèles courants

Pipeline CI/CD

# 1. Vérifier les modifications de schéma
rover subgraph check $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql

# 2. Si la vérification réussit, publier
rover subgraph publish $APOLLO_GRAPH_REF \
  --name $SUBGRAPH_NAME \
  --schema ./schema.graphql \
  --routing-url $ROUTING_URL

Linting de schéma

# Linter selon les règles GraphOS
rover subgraph lint --name products ./schema.graphql

# Linter monograph
rover graph lint my-graph@production ./schema.graphql

Formats de sortie

# Sortie JSON pour les scripts
rover subgraph fetch my-graph@production --name products --format json

# Sortie brute (par défaut)
rover subgraph fetch my-graph@production --name products --format plain

Règles de base

• TOUJOURS s'authentifier avant d'utiliser les commandes GraphOS (rover config auth ou APOLLO_KEY)
• TOUJOURS utiliser le format de référence de graphe correct : graph@variant
• PRÉFÉRER rover subgraph check avant rover subgraph publish en CI/CD
• UTILISER rover dev pour le développement de supergraph local au lieu d'exécuter Router manuellement
• NE JAMAIS valider APOLLO_KEY dans le contrôle de version ; utiliser les variables d'environnement
• UTILISER --format json lors de l'analyse de la sortie par programmation
• SPÉCIFIER federation_version explicitement dans supergraph.yaml pour la reproductibilité
• UTILISER rover subgraph introspect pour extraire les schémas des services en cours d'exécution