rover

Apollo Rover CLI ガイド

Rover は Apollo GraphOS の公式 CLI です。スキーマの管理、ローカルでのコンポジションの実行、GraphOS への公開、ローカルマシンでのスーパーグラフの開発に役立ちます。

クイックスタート

ステップ 1：インストール

# 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

ステップ 2：認証

# OAuth login via browser (recommended for local dev)
rover auth login

# Or interactive API key entry
rover config auth

# Or set environment variable (recommended for CI/CD)
export APOLLO_KEY=your-api-key

ステップ 3：インストールの確認

rover --version
rover auth whoami    # OAuth identity
rover config whoami  # API key identity

ステップ 4：プロジェクトの初期化（任意）

# Create a new federated graph project
rover init

# Create a project with MCP server
rover init --mcp

グラフのスキーマを調べる（スキーマに関する質問はここから始めてください）

「このグラフには何があるか」を確認したり、フィールドを探したり、GraphOS のグラフに対するクエリを作成したりするには、API スキーマを取得して rover schema にパイプで渡します。これにより、SDL がコンテキストに含まれるのを避け、必要な情報だけが返されます。

# 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

正確性を保つための 3 つのルール：

• rover graph fetch（API スキーマ）を使用します。rover supergraph fetch（join__／link__ のようなフェデレーション内部情報を含むコンポジション SDL を返します）は使用しないでください。
• パイプで渡します。rover graph fetch だけを実行して生の SDL を読み取らないでください（大きなスキーマはコンテキストを圧迫します。これを避けるのが rover schema の役割です）。
• schema コマンドが読み取るのはパイプで渡された SDL であり、グラフ参照ではありません。rover schema describe <graph@variant> は失敗します。先に取得してパイプで渡す必要があります。

完全なリファレンス、優先順位付けのルール、保存を一度だけ行うパターンについては、スキーマの探索 と references/schema.md を参照してください。

主なコマンドの概要

コマンド	説明	用途
rover init	新しいフェデレーショングラフプロジェクトを初期化します	新規プロジェクトのセットアップ、MCP サーバーのセットアップ
rover subgraph publish	サブグラフスキーマを GraphOS に公開します	CI/CD、スキーマの更新
rover subgraph check	スキーマの変更を検証します	PR チェック、デプロイ前
rover subgraph fetch	サブグラフスキーマをダウンロードします	ローカル開発
rover supergraph compose	スーパーグラフをローカルでコンポーズします	ローカルテスト
rover dev	ローカルでのスーパーグラフ開発	開発ワークフロー
rover graph publish	モノグラフスキーマを公開します	非フェデレーショングラフ
rover schema describe	座標でスキーマを調べます。グラフ参照ではなく、stdin／ファイルから SDL を受け取ります。rover graph fetch からパイプで渡してください	エージェントによるスキーマの探索
rover schema search	キーワードでスキーマを検索します。グラフ参照ではなく、stdin／ファイルから SDL を受け取ります。rover graph fetch からパイプで渡してください	エージェントによるスキーマの探索
rover connector	Apollo Connectors を操作します（実行、テスト、一覧表示）	コネクター開発
rover contract	コントラクトバリアントを管理します（説明、プレビュー、公開）	API サーフェスのフィルタリング
rover persisted-queries	永続クエリマニフェストを生成して公開します（エイリアス：pq）	セキュリティ、パフォーマンス
rover client check	クライアント操作をグラフスキーマに対して検証します	クライアント側 CI
rover auth login	OAuth ブラウザーフローで認証します	ローカル開発の認証
rover api-key	API キーの作成、一覧表示、削除、名前変更、ローテーションを行います	キー管理
rover readme	グラフバリアントの README を取得または公開します	グラフのドキュメント
rover template	プロジェクトテンプレートを一覧表示して使用します	スキャフォールディング

グラフ参照の形式

ほとんどのコマンドでは、次の形式のグラフ参照が必要です。

<GRAPH_ID>@<VARIANT>

例：

• my-graph@production
• my-graph@staging
• my-graph@current（デフォルトのバリアント）

環境変数として設定します：

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

スーパーグラフのコンポジション

ローカルでのコンポジション

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 はコンポジションのバージョンです。各サブグラフの @link の下限以上であればよいため、より低いバージョンに固定されたサブグラフも問題なくコンポーズできます。起動時にサブグラフサーバーが UNKNOWN_FEDERATION_LINK_VERSION を返す場合、これはクライアントライブラリの対応遅れであり、コンポジションの問題ではありません。apollo-federation スキルのフェデレーションのバージョンを参照してください。

コンポーズします：

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

合成済みスーパーグラフの取得

rover supergraph fetch my-graph@production

これは スーパーグラフ SDL（フェデレーションディレクティブと join__／link__ の内部要素）を返します。コンポジションやルーター関連の作業に使用してください。クエリ可能な内容を確認する場合やオペレーションを作成する場合は、代わりに rover graph fetch（API スキーマ）を使用してください。詳しくはグラフのスキーマを確認するを参照してください。

rover dev によるローカル開発

スキーマを自動で合成するローカルルーターを起動します。

# 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

MCP との連携

# Start with MCP server enabled
rover dev --supergraph-config supergraph.yaml --mcp

スキーマの確認（エージェント向け）

rover schema describe と rover schema search を使うと、完全な SDL をコンテキストに読み込まずにエージェントがスキーマを確認できます。これが、これらのコマンドの目的そのものです。

⚠️ 生の SDL をコンテキストに読み込まないでください。 rover graph fetch <ref>（または rover graph introspect <url>）を単独で実行すると、スキーマ全体（数百行から数万行）がそのままコンテキストに出力され、これらのコマンドを使う意味がなくなります。取得結果は必ず rover schema describe／search にパイプしてください。SDL は stdin を通じて渡され、コンパクトな概要や検索結果だけが出力されます。（ユーザーが実際に SDL を求めている場合は、ファイルに取得しても問題ありません。）

これらのコマンドは、SDL を stdin またはファイルから受け取ります。グラフ参照からは受け取りません。graph@variant を渡すことはできません。先に取得してからパイプしてください。

❌ rover schema describe my-graph@current             # エラー：その名前のファイルを探します
❌ rover graph fetch my-graph@current                 # SDL 全体をコンテキストに出力します
✅ rover graph fetch my-graph@current | rover schema describe -

GraphOS のグラフを確認するには、スキーマを取得してパイプで渡します。「何をクエリできますか？」という確認には、rover graph fetch（API スキーマ）を使用してください。フェデレーション内部要素は含まれません。コンポジションの詳細（join__／link__ の型、サブグラフ構造）が必要な場合に限り、rover supergraph fetch を使用してください。

# 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

座標の形式： --coord には、型（User）、フィールド（User.posts）、フィールド引数（Type.field(arg:)）、またはディレクティブ（@deprecated）を指定できます。概要を表示する場合は省略してください。

search と describe の使い分け： 概念やキーワードに一致する項目を探していて、フィールド名がまだわからない場合は、まず rover schema search を使用してください。ネストされたフィールドも見つけ、ルートオペレーションからのパスを表示します。describe の概要に表示されるのはルートフィールドのみなので、より深い階層にあるフィールドを見つけるには search を使います。概要を確認する場合や、型／フィールドの座標がわかっている場合は describe を使用してください。

これにより、MCP サーバーをセットアップせずに、検索 → 詳細確認 → クエリ作成という一連のワークフローを完結できます。すべてのコマンドリファレンス、ランキングルール、大規模スキーマ向けの一度だけ保存するパターンについては、スキーマの確認を参照してください。

生成したオペレーションの実行： Rover はクエリを実行せず、スキーマの管理と確認のみを行います。生成したクエリを実際に実行するには、グラフのエンドポイントが必要です。

• 単一サブグラフのグラフ： rover subgraph list <graph@variant> を実行すると Routing Url が表示されます。そこに curl でクエリを送信してください。
• マルチサブグラフ／フェデレーション： クライアントのエンドポイントはルーターの URL です（GraphOS Studio で確認してください）。サブグラフごとのルーティング URL ではありません。
• GraphOS Platform API を使ってエンドポイントを調べようとしないでください。Rover は API キーをプロファイル／キーチェーンに保存しており、$APOLLO_KEY には保存していないため、その場しのぎの API 呼び出しは認証されずに失敗します。

参考ファイル

トピックごとの詳しいドキュメント：

• 初期化 - rover init によるプロジェクトの初期化と MCP サーバーのセットアップ
• サブグラフ - 取得、公開、チェック、リント、イントロスペクション、削除
• グラフ - モノグラフのコマンド（フェデレーションなし）
• スーパーグラフ - 構成、取得、設定形式
• 開発 - ローカル開発向けの rover dev
• スキーマの調査 - スキーマの説明、検索、エージェントによるスキーマ探索のワークフロー
• コネクター - rover connector の実行、テスト、一覧表示、分析、生成
• コントラクト - コントラクトバリアントの説明、プレビュー、公開
• 永続化クエリ - 永続化クエリマニフェストの生成と公開
• クライアント操作 - クライアント操作の検証、GraphQL ドキュメントの抽出
• 設定 - インストール、認証、環境変数、プロファイル、OAuth ログイン
• その他のコマンド - template、readme、api-key、plugin、license、graph-artifact、completion、explain、docs

よくあるパターン

CI/CD パイプライン

# 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

基本ルール

• GraphOS コマンドを使用する前に、必ず認証してください（rover auth login、rover config auth、または APOLLO_KEY）
• 正しいグラフ参照形式 graph@variant を必ず使用してください
• CI/CD では、rover subgraph publish の前に rover subgraph check を使用してください
• ローカルでスーパーグラフを開発する場合は、Router を手動で実行する代わりに rover dev を使用してください
• 新しいグラフプロジェクトを作成する場合は、手動でセットアップする代わりに rover init を使用してください
• APOLLO_KEY や APOLLO_CLIENT_SECRET をバージョン管理にコミットしないでください。環境変数を使用してください
• プログラムで出力を解析する場合は、--format json を使用してください
• 再現性を確保するため、supergraph.yaml では federation_version を明示的に指定してください
• 実行中のサービスからスキーマを抽出するには、rover subgraph introspect を使用してください
• 大きなスキーマを調べる場合は、SDL 全体をコンテキストに読み込む代わりに、rover schema search／rover schema describe（fetch からパイプで渡す）を使用してください
• 調査するだけの目的でスキーマ全体をコンテキストに取得しないでください。rover graph fetch／introspect の出力を rover schema describe／search にパイプで渡してください（単独の fetch は、ユーザーが SDL ファイル自体を必要としている場合にのみ使用します）
• クライアントの変更をデプロイする前に、クライアント操作を検証するため rover client check を使用してください
• 永続化クエリの強制適用に向けて操作を登録するには、rover persisted-queries publish を使用してください