rover

Original source / Raw SKILL.md

---
name: rover
description: >
  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.
license: MIT
compatibility: Node.js v18+, Linux/macOS/Windows
metadata:
  author: apollographql
  version: "1.0.1"
allowed-tools: Bash(rover:*) Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
---

# Apollo Rover CLI Guide

Rover is the official CLI for Apollo GraphOS. It helps you manage schemas, run composition locally, publish to GraphOS, and develop supergraphs on your local machine.

## Quick Start

### Step 1: Install

```bash
# 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
```

### Step 2: Authenticate

```bash
# Interactive authentication (opens browser)
rover config auth

# Or set environment variable
export APOLLO_KEY=your-api-key
```

### Step 3: Verify Installation

```bash
rover --version
rover config whoami
```

## Core Commands Overview

| Command | Description | Use Case |
|---------|-------------|----------|
| `rover subgraph publish` | Publish subgraph schema to GraphOS | CI/CD, schema updates |
| `rover subgraph check` | Validate schema changes | PR checks, pre-deploy |
| `rover subgraph fetch` | Download subgraph schema | Local development |
| `rover supergraph compose` | Compose supergraph locally | Local testing |
| `rover dev` | Local supergraph development | Development workflow |
| `rover graph publish` | Publish monograph schema | Non-federated graphs |

## Graph Reference Format

Most commands require a graph reference in the format:

```
<GRAPH_ID>@<VARIANT>
```

Examples:
- `my-graph@production`
- `my-graph@staging`
- `my-graph@current` (default variant)

Set as environment variable:
```bash
export APOLLO_GRAPH_REF=my-graph@production
```

## Subgraph Workflow

### Publishing a Subgraph

```bash
# 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
```

### Checking Schema Changes

```bash
# Check against production traffic
rover subgraph check my-graph@production \
  --name products \
  --schema ./schema.graphql
```

### Fetching Schema

```bash
# Fetch from GraphOS
rover subgraph fetch my-graph@production --name products

# Introspect running server
rover subgraph introspect http://localhost:4001/graphql
```

## Supergraph Composition

### Local Composition

Create `supergraph.yaml`:

```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
```

Compose:
```bash
rover supergraph compose --config supergraph.yaml > supergraph.graphql
```

### Fetch Composed Supergraph

```bash
rover supergraph fetch my-graph@production
```

## Local Development with `rover dev`

Start a local Router with automatic schema composition:

```bash
# 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
```

### With MCP Integration

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

## Reference Files

Detailed documentation for specific topics:

- [Subgraphs](references/subgraphs.md) - fetch, publish, check, lint, introspect, delete
- [Graphs](references/graphs.md) - monograph commands (non-federated)
- [Supergraphs](references/supergraphs.md) - compose, fetch, config format
- [Dev](references/dev.md) - rover dev for local development
- [Configuration](references/configuration.md) - install, auth, env vars, profiles

## Common Patterns

### CI/CD Pipeline

```bash
# 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
```

### Schema Linting

```bash
# Lint against GraphOS rules
rover subgraph lint --name products ./schema.graphql

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

### Output Formats

```bash
# 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
```

## Ground Rules

- ALWAYS authenticate before using GraphOS commands (`rover config auth` or `APOLLO_KEY`)
- ALWAYS use the correct graph reference format: `graph@variant`
- PREFER `rover subgraph check` before `rover subgraph publish` in CI/CD
- USE `rover dev` for local supergraph development instead of running Router manually
- NEVER commit `APOLLO_KEY` to version control; use environment variables
- USE `--format json` when parsing output programmatically
- SPECIFY `federation_version` explicitly in supergraph.yaml for reproducibility
- USE `rover subgraph introspect` to extract schemas from running services


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/subgraphs.md

```markdown
# Rover Subgraph Commands

Commands for managing federated subgraph schemas in Apollo GraphOS.

## subgraph fetch

Download a subgraph schema from GraphOS.

```bash
# Basic fetch
rover subgraph fetch my-graph@production --name products

# Output to file
rover subgraph fetch my-graph@production --name products > products.graphql

# JSON output
rover subgraph fetch my-graph@production --name products --format json
```

**Options:**
| Option | Description |
|--------|-------------|
| `--name <NAME>` | Subgraph name (required) |
| `--format <FORMAT>` | Output format: `plain` (default) or `json` |

## subgraph introspect

Extract schema from a running GraphQL server via introspection.

```bash
# Basic introspection
rover subgraph introspect http://localhost:4001/graphql

# With headers
rover subgraph introspect http://localhost:4001/graphql \
  --header "Authorization: Bearer token123"

# Multiple headers
rover subgraph introspect http://localhost:4001/graphql \
  --header "Authorization: Bearer token" \
  --header "X-Custom-Header: value"

# Watch mode (poll for changes)
rover subgraph introspect http://localhost:4001/graphql --watch
```

**Options:**
| Option | Description |
|--------|-------------|
| `--header <HEADER>` | HTTP header(s) to include |
| `--watch` | Poll endpoint and output changes |
| `--polling-interval <SECONDS>` | Interval for watch mode (default: 1) |

## subgraph list

List all subgraphs in a graph variant.

```bash
rover subgraph list my-graph@production
```

**Output includes:**
- Subgraph name
- Routing URL
- Last updated timestamp

## subgraph publish

Publish a subgraph schema to GraphOS.

```bash
# From file
rover subgraph publish my-graph@production \
  --name products \
  --schema ./products.graphql \
  --routing-url https://products.example.com/graphql

# From stdin (introspection)
rover subgraph introspect http://localhost:4001/graphql | \
  rover subgraph publish my-graph@production \
    --name products \
    --schema - \
    --routing-url https://products.example.com/graphql

# Process substitution
rover subgraph publish my-graph@production \
  --name products \
  --schema <(rover subgraph introspect http://localhost:4001/graphql) \
  --routing-url https://products.example.com/graphql
```

**Options:**
| Option | Description |
|--------|-------------|
| `--name <NAME>` | Subgraph name (required) |
| `--schema <PATH>` | Schema file path or `-` for stdin (required) |
| `--routing-url <URL>` | URL where Router sends requests |
| `--allow-invalid-routing-url` | Allow non-HTTPS or non-standard URLs |
| `--no-url` | Skip URL update (schema only) |

**Routing URL:**
- Required on first publish
- Optional on subsequent publishes (uses existing if not provided)
- Must be reachable by the Router in production

## subgraph check

Validate schema changes against GraphOS.

```bash
# Basic check
rover subgraph check my-graph@production \
  --name products \
  --schema ./products.graphql

# Check with specific validation period
rover subgraph check my-graph@production \
  --name products \
  --schema ./products.graphql \
  --query-count-threshold 1000 \
  --query-count-threshold-percentage 5
```

**Check validates:**
1. **Composition** - Schema composes successfully with other subgraphs
2. **Operations** - Existing client operations still work
3. **Linting** - Schema follows GraphOS linting rules

**Options:**
| Option | Description |
|--------|-------------|
| `--name <NAME>` | Subgraph name (required) |
| `--schema <PATH>` | Schema file path (required) |
| `--query-count-threshold <N>` | Min operations for breaking change |
| `--query-count-threshold-percentage <N>` | Min % of operations |
| `--background` | Run check in background (returns check ID) |

**Exit codes:**
- `0` - Check passed
- `1` - Check failed (breaking changes or errors)
- `2` - Check completed with warnings

## subgraph lint

Run GraphOS linting rules against a schema.

```bash
# Lint local schema
rover subgraph lint --name products ./products.graphql

# Lint with specific graph for rules
rover subgraph lint my-graph@production --name products ./products.graphql
```

**Common lint rules:**
- Field naming conventions
- Description requirements
- Deprecation format
- Federation directive usage

## subgraph delete

Remove a subgraph from a graph variant.

```bash
# Delete with confirmation prompt
rover subgraph delete my-graph@production --name products

# Delete without confirmation
rover subgraph delete my-graph@production --name products --confirm
```

**Warning:** Deleting a subgraph:
- Removes it from composition
- May break client operations that use its types
- Cannot be undone (must republish)

**Options:**
| Option | Description |
|--------|-------------|
| `--name <NAME>` | Subgraph name (required) |
| `--confirm` | Skip confirmation prompt |

## Introspection Headers

For authenticated endpoints:

```bash
# Bearer token
rover subgraph introspect http://localhost:4001/graphql \
  --header "Authorization: Bearer $(cat token.txt)"

# API key
rover subgraph introspect http://localhost:4001/graphql \
  --header "x-api-key: my-api-key"

# From environment variable
rover subgraph introspect http://localhost:4001/graphql \
  --header "Authorization: Bearer $AUTH_TOKEN"
```

## Combining Commands

### Publish from running server

```bash
rover subgraph publish my-graph@production \
  --name products \
  --schema <(rover subgraph introspect http://localhost:4001/graphql) \
  --routing-url https://products.example.com/graphql
```

### Check then publish

```bash
# In CI/CD pipeline
rover subgraph check my-graph@production \
  --name products \
  --schema ./products.graphql && \
rover subgraph publish my-graph@production \
  --name products \
  --schema ./products.graphql \
  --routing-url https://products.example.com/graphql
```

### Fetch all subgraphs

```bash
# List and fetch each
for name in $(rover subgraph list my-graph@production --format json | jq -r '.data.subgraphs[].name'); do
  rover subgraph fetch my-graph@production --name "$name" > "$name.graphql"
done
```

```

### references/graphs.md

```markdown
# Rover Graph Commands

Commands for managing monograph (non-federated) schemas in Apollo GraphOS.

> **Note:** Use `rover subgraph` commands for federated graphs. These `rover graph` commands are for standalone GraphQL APIs without federation.

## graph fetch

Download a graph schema from GraphOS.

```bash
# Basic fetch
rover graph fetch my-graph@production

# Output to file
rover graph fetch my-graph@production > schema.graphql

# JSON output
rover graph fetch my-graph@production --format json
```

**Options:**
| Option | Description |
|--------|-------------|
| `--format <FORMAT>` | Output format: `plain` (default) or `json` |

## graph introspect

Extract schema from a running GraphQL server.

```bash
# Basic introspection
rover graph introspect http://localhost:4000/graphql

# With authentication header
rover graph introspect http://localhost:4000/graphql \
  --header "Authorization: Bearer token123"

# Multiple headers
rover graph introspect http://localhost:4000/graphql \
  --header "Authorization: Bearer token" \
  --header "X-Tenant-ID: acme"

# Watch mode
rover graph introspect http://localhost:4000/graphql --watch
```

**Options:**
| Option | Description |
|--------|-------------|
| `--header <HEADER>` | HTTP header(s) to include |
| `--watch` | Poll endpoint and output changes |
| `--polling-interval <SECONDS>` | Interval for watch mode (default: 1) |

## graph publish

Publish a monograph schema to GraphOS.

```bash
# From file
rover graph publish my-graph@production \
  --schema ./schema.graphql

# From stdin
cat schema.graphql | rover graph publish my-graph@production --schema -

# From introspection
rover graph publish my-graph@production \
  --schema <(rover graph introspect http://localhost:4000/graphql)
```

**Options:**
| Option | Description |
|--------|-------------|
| `--schema <PATH>` | Schema file path or `-` for stdin (required) |

## graph check

Validate schema changes against GraphOS.

```bash
# Basic check
rover graph check my-graph@production \
  --schema ./schema.graphql

# With validation thresholds
rover graph check my-graph@production \
  --schema ./schema.graphql \
  --query-count-threshold 100 \
  --query-count-threshold-percentage 3
```

**Check validates:**
1. **Schema validity** - Schema is syntactically correct
2. **Operations** - Existing client operations still work
3. **Linting** - Schema follows GraphOS linting rules

**Options:**
| Option | Description |
|--------|-------------|
| `--schema <PATH>` | Schema file path (required) |
| `--query-count-threshold <N>` | Min operations for breaking change |
| `--query-count-threshold-percentage <N>` | Min % of operations |
| `--background` | Run check in background |

**Exit codes:**
- `0` - Check passed
- `1` - Check failed
- `2` - Check completed with warnings

## graph lint

Run GraphOS linting rules against a schema.

```bash
# Lint local schema (uses graph for rule configuration)
rover graph lint my-graph@production --schema ./schema.graphql

# Lint without graph reference
rover graph lint --schema ./schema.graphql
```

## graph delete

Delete a graph variant from GraphOS.

```bash
# Delete with confirmation
rover graph delete my-graph@staging

# Delete without confirmation
rover graph delete my-graph@staging --confirm
```

**Warning:** This deletes the entire variant, not just the schema.

**Options:**
| Option | Description |
|--------|-------------|
| `--confirm` | Skip confirmation prompt |

## Differences from Subgraph Commands

| Aspect | `rover graph` | `rover subgraph` |
|--------|---------------|------------------|
| Use case | Monographs | Federated subgraphs |
| Routing URL | Not required | Required for Router |
| Composition | N/A | Composes with other subgraphs |
| `--name` flag | Not used | Required |

## Migration to Federation

If migrating from a monograph to federation:

```bash
# 1. Fetch existing monograph schema
rover graph fetch my-graph@production > schema.graphql

# 2. Add federation directives to schema
# (edit schema.graphql to add @key, extend Query, etc.)

# 3. Publish as first subgraph
rover subgraph publish my-graph@production \
  --name monolith \
  --schema ./schema.graphql \
  --routing-url https://api.example.com/graphql
```

## CI/CD Example

```bash
#!/bin/bash
set -e

GRAPH_REF="${APOLLO_GRAPH_REF:-my-graph@production}"
SCHEMA_PATH="./schema.graphql"

# Check schema changes
echo "Checking schema..."
rover graph check "$GRAPH_REF" --schema "$SCHEMA_PATH"

# Publish if check passes
echo "Publishing schema..."
rover graph publish "$GRAPH_REF" --schema "$SCHEMA_PATH"

echo "Schema published successfully!"
```

```

### references/supergraphs.md

```markdown
# Rover Supergraph Commands

Commands for composing and fetching federated supergraph schemas.

## supergraph fetch

Download the composed supergraph schema from GraphOS.

```bash
# Basic fetch
rover supergraph fetch my-graph@production

# Output to file
rover supergraph fetch my-graph@production > supergraph.graphql

# JSON output (includes build info)
rover supergraph fetch my-graph@production --format json
```

**Options:**
| Option | Description |
|--------|-------------|
| `--format <FORMAT>` | Output format: `plain` (default) or `json` |

**Output:** The full supergraph SDL including:
- All subgraph types merged
- Federation metadata (`_service`, `_entities`)
- Join directives for Router

## supergraph compose

Compose a supergraph schema locally from subgraph schemas.

```bash
# Basic composition
rover supergraph compose --config supergraph.yaml

# Output to file
rover supergraph compose --config supergraph.yaml > supergraph.graphql

# Specify output file
rover supergraph compose --config supergraph.yaml --output supergraph.graphql
```

**Options:**
| Option | Description |
|--------|-------------|
| `--config <PATH>` | Path to supergraph config file (required) |
| `--output <PATH>` | Write output to file |
| `--format <FORMAT>` | Output format: `plain` (default) or `json` |

## Supergraph Configuration File

The `supergraph.yaml` file defines subgraphs for local composition.

### Basic Structure

```yaml
federation_version: =2.9.0

subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./subgraphs/products/schema.graphql

  reviews:
    routing_url: http://localhost:4002/graphql
    schema:
      file: ./subgraphs/reviews/schema.graphql

  users:
    routing_url: http://localhost:4003/graphql
    schema:
      subgraph_url: http://localhost:4003/graphql
```

### Schema Sources

#### From File

```yaml
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./products.graphql
```

#### From Introspection

```yaml
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      subgraph_url: http://localhost:4001/graphql
```

#### From Introspection with Headers

```yaml
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      subgraph_url: http://localhost:4001/graphql
      introspection_headers:
        Authorization: Bearer ${AUTH_TOKEN}
        X-Custom-Header: value
```

#### From GraphOS

```yaml
subgraphs:
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      graphref: my-graph@production
      subgraph: products
```

### Federation Version

```yaml
# Exact version (recommended for reproducibility)
federation_version: =2.9.0

# Minimum version
federation_version: 2.9.0

# Latest 2.x
federation_version: 2
```

**Supported versions:**
- `2.9.x` - Latest with `@cost` directive
- `2.8.x` - Stable with `@context`
- `2.7.x` - `@authenticated`, `@requiresScopes`
- `1.x` - Legacy (not recommended)

### Complete Example

```yaml
federation_version: =2.9.0

subgraphs:
  # From local files (development)
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./services/products/schema.graphql

  # From running service (hot reload)
  inventory:
    routing_url: http://localhost:4002/graphql
    schema:
      subgraph_url: http://localhost:4002/graphql

  # From GraphOS (production baseline)
  users:
    routing_url: http://localhost:4003/graphql
    schema:
      graphref: my-graph@production
      subgraph: users

  # With authentication
  orders:
    routing_url: http://localhost:4004/graphql
    schema:
      subgraph_url: http://localhost:4004/graphql
      introspection_headers:
        Authorization: Bearer ${ORDERS_TOKEN}
```

## Composition Errors

### Common Errors

**Entity Key Mismatch:**
```
Error: Entity "Product" has different keys in different subgraphs
```
Fix: Ensure `@key` directives match across subgraphs.

**Invalid Reference:**
```
Error: Cannot extend type "Product" - not found in any subgraph
```
Fix: Define the base type in one subgraph before extending.

**Field Conflict:**
```
Error: Field "Product.name" has different types in different subgraphs
```
Fix: Ensure field types match or use `@override`.

### Debugging Composition

```bash
# Verbose output
rover supergraph compose --config supergraph.yaml 2>&1 | head -100

# JSON output includes detailed errors
rover supergraph compose --config supergraph.yaml --format json
```

## Using with Router

### Local Development

```bash
# 1. Compose supergraph
rover supergraph compose --config supergraph.yaml > supergraph.graphql

# 2. Run Router with composed schema
router --supergraph supergraph.graphql
```

### With rover dev (Recommended)

```bash
# Automatic composition and Router
rover dev --supergraph-config supergraph.yaml
```

## Environment Variables

Use environment variables in config:

```yaml
subgraphs:
  products:
    routing_url: ${PRODUCTS_URL}
    schema:
      subgraph_url: ${PRODUCTS_URL}
      introspection_headers:
        Authorization: Bearer ${PRODUCTS_TOKEN}
```

```bash
PRODUCTS_URL=http://localhost:4001/graphql \
PRODUCTS_TOKEN=secret \
  rover supergraph compose --config supergraph.yaml
```

## CI/CD Integration

### Validate Composition

```bash
# Fail if composition errors
rover supergraph compose --config supergraph.yaml > /dev/null
echo "Composition successful"
```

### Compare with Production

```bash
# Fetch production supergraph
rover supergraph fetch my-graph@production > production.graphql

# Compose local
rover supergraph compose --config supergraph.yaml > local.graphql

# Diff schemas
diff production.graphql local.graphql
```

```

### references/dev.md

```markdown
# Rover Dev Command

Run a local supergraph for development with automatic schema composition and hot reloading.

## Basic Usage

```bash
# Start with supergraph config
rover dev --supergraph-config supergraph.yaml

# Start on specific port
rover dev --supergraph-config supergraph.yaml --router-port 4000
```

**Default behavior:**
- Router runs on `http://localhost:4000`
- GraphQL endpoint: `http://localhost:4000`
- Health check: `http://localhost:4000/health`

## Configuration File

Create `supergraph.yaml` for local development:

```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

  users:
    routing_url: http://localhost:4003/graphql
    schema:
      file: ./users/schema.graphql
```

## Hot Reloading

### File-based Schema

When using `schema.file`, Rover watches for file changes:

```yaml
subgraphs:
  products:
    schema:
      file: ./products/schema.graphql  # Watched for changes
```

Save the file and Rover automatically recomposes.

### Introspection-based Schema

When using `schema.subgraph_url`, Rover polls for changes:

```yaml
subgraphs:
  reviews:
    schema:
      subgraph_url: http://localhost:4002/graphql  # Polled for changes
```

## Using with GraphOS Variant

Start with a GraphOS variant as baseline and override locally:

```bash
rover dev --graph-ref my-graph@staging --supergraph-config local-overrides.yaml
```

**local-overrides.yaml:**
```yaml
federation_version: =2.9.0

subgraphs:
  # Override products with local version
  products:
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./products/schema.graphql
  # Other subgraphs come from GraphOS variant
```

## Router Configuration

### Custom Router Config

```bash
rover dev \
  --supergraph-config supergraph.yaml \
  --router-config router.yaml
```

**router.yaml:**
```yaml
supergraph:
  listen: 127.0.0.1:4000

headers:
  all:
    request:
      - propagate:
          matching: "^x-.*"

cors:
  origins:
    - http://localhost:3000
  allow_headers:
    - Content-Type
    - Authorization

telemetry:
  apollo:
    endpoint: https://usage.api.apollographql.com/api/ingress/traces
```

### Common Router Options

```yaml
# Sandbox enabled (default in dev)
sandbox:
  enabled: true

# Introspection enabled (default in dev)
introspection: true

# Query plans in response
include_subgraph_errors:
  all: true
```

## MCP Server Integration

Enable MCP server alongside Router:

```bash
rover dev --supergraph-config supergraph.yaml --mcp
```

**MCP options:**
```bash
# Specify MCP port
rover dev --supergraph-config supergraph.yaml --mcp --mcp-port 5001

# MCP output format
rover dev --supergraph-config supergraph.yaml --mcp --mcp-format json
```

**Use cases:**
- AI agent integration during development
- Testing MCP-based tools
- Local agentic workflow development

## Multiple Subgraph Development

### Single Machine Setup

```bash
# Terminal 1: Products subgraph
cd products && npm run dev  # Runs on 4001

# Terminal 2: Reviews subgraph
cd reviews && npm run dev   # Runs on 4002

# Terminal 3: Rover dev
rover dev --supergraph-config supergraph.yaml
```

### Adding a New Subgraph

1. Add to `supergraph.yaml`:
```yaml
subgraphs:
  # existing...

  new-service:
    routing_url: http://localhost:4004/graphql
    schema:
      file: ./new-service/schema.graphql
```

2. Rover automatically detects changes and recomposes.

## Options Reference

| Option | Description | Default |
|--------|-------------|---------|
| `--supergraph-config <PATH>` | Path to supergraph config | Required |
| `--graph-ref <REF>` | GraphOS variant for baseline | None |
| `--router-port <PORT>` | Router listen port | 4000 |
| `--router-config <PATH>` | Custom Router config | None |
| `--mcp` | Enable MCP server | false |
| `--mcp-port <PORT>` | MCP server port | 5001 |
| `--log <LEVEL>` | Log level | info |

## Troubleshooting

### Port Already in Use

```bash
# Check what's using port 4000
lsof -i :4000

# Use different port
rover dev --supergraph-config supergraph.yaml --router-port 4001
```

### Subgraph Not Reachable

```
Error: Could not connect to subgraph "products" at http://localhost:4001/graphql
```

- Ensure subgraph server is running
- Check correct port in config
- Verify subgraph URL responds to introspection

### Composition Fails

```bash
# Check composition separately
rover supergraph compose --config supergraph.yaml

# Look for specific errors in output
```

### Schema Not Updating

For file-based schemas:
- Ensure file path is correct
- Check file permissions
- Try saving file again

For introspection:
- Ensure server has introspection enabled
- Check for authentication requirements

## Environment Variables

```bash
# Required for GraphOS features
export APOLLO_KEY=your-api-key
export APOLLO_GRAPH_REF=my-graph@staging

# Run with environment
APOLLO_KEY=$APOLLO_KEY rover dev \
  --graph-ref $APOLLO_GRAPH_REF \
  --supergraph-config local.yaml
```

## Development Workflow

### Typical Session

```bash
# 1. Start subgraph servers
npm run dev:subgraphs  # Custom script to start all

# 2. Start Rover dev
rover dev --supergraph-config supergraph.yaml

# 3. Open http://localhost:4000 for Sandbox
# 4. Make schema changes - auto-reloads
# 5. Ctrl+C to stop
```

### With Docker Compose

```yaml
# docker-compose.yaml
services:
  products:
    build: ./products
    ports:
      - "4001:4001"

  reviews:
    build: ./reviews
    ports:
      - "4002:4002"
```

```bash
# Start services
docker-compose up -d

# Start Rover dev
rover dev --supergraph-config supergraph.yaml
```

```

### references/configuration.md

```markdown
# Rover Configuration

Installation, authentication, and environment configuration for Apollo Rover CLI.

## Installation

### macOS and Linux

```bash
# Install latest version
curl -sSL https://rover.apollo.dev/nix/latest | sh

# Install specific version
curl -sSL https://rover.apollo.dev/nix/v0.26.0 | sh

# Add to PATH (if not automatic)
export PATH="$HOME/.rover/bin:$PATH"
```

### npm (Cross-platform)

```bash
# Global install
npm install -g @apollo/rover

# Project-local install
npm install --save-dev @apollo/rover
npx rover --version
```

### Windows PowerShell

```powershell
# Install latest
iwr 'https://rover.apollo.dev/win/latest' | iex

# Install specific version
iwr 'https://rover.apollo.dev/win/v0.26.0' | iex
```

### Verify Installation

```bash
rover --version
rover --help
```

## Authentication

### Interactive Authentication

```bash
# Opens browser for authentication
rover config auth
```

**Process:**
1. Browser opens to GraphOS Studio
2. Log in or create account
3. Authorize Rover
4. Token saved to config file

### API Key Authentication

```bash
# Set via environment variable (recommended for CI/CD)
export APOLLO_KEY=your-api-key

# Or configure directly
rover config auth --api-key your-api-key
```

### Verify Authentication

```bash
# Check current authentication
rover config whoami
```

**Output:**
```
Authenticated as: [email protected]
Organization: My Org
API Key Type: User
```

## Environment Variables

### Core Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `APOLLO_KEY` | API key for GraphOS | `user:gh.xxx:yyy` |
| `APOLLO_GRAPH_REF` | Default graph reference | `my-graph@production` |

### Using Environment Variables

```bash
# Set in shell
export APOLLO_KEY=your-api-key
export APOLLO_GRAPH_REF=my-graph@production

# Use in commands
rover subgraph fetch $APOLLO_GRAPH_REF --name products

# Or commands auto-detect APOLLO_GRAPH_REF
rover subgraph fetch --name products
```

### CI/CD Environment

```yaml
# GitHub Actions
env:
  APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
  APOLLO_GRAPH_REF: my-graph@production

steps:
  - run: rover subgraph check $APOLLO_GRAPH_REF --name products --schema ./schema.graphql
```

```yaml
# CircleCI
environment:
  APOLLO_KEY: ${APOLLO_KEY}
  APOLLO_GRAPH_REF: my-graph@production
```

## Configuration File

Rover stores configuration in `~/.rover/config.toml`.

### Location

```bash
# View config path
rover config list

# macOS/Linux: ~/.rover/config.toml
# Windows: %USERPROFILE%\.rover\config.toml
```

### Structure

```toml
[profiles.default]
api_key = "user:gh.xxx:yyy"

[profiles.staging]
api_key = "user:gh.xxx:zzz"
```

## Profiles

Use profiles for different environments or accounts.

### Create Profile

```bash
# Create/update profile
rover config auth --profile staging
```

### Use Profile

```bash
# Specify profile for command
rover subgraph fetch my-graph@staging --name products --profile staging
```

### List Profiles

```bash
rover config list
```

## Output Formats

### Plain Text (Default)

```bash
rover subgraph fetch my-graph@production --name products
```

Output: Raw SDL schema

### JSON

```bash
rover subgraph fetch my-graph@production --name products --format json
```

Output:
```json
{
  "data": {
    "sdl": "type Product { ... }",
    "name": "products"
  },
  "error": null
}
```

### Using with jq

```bash
# Extract just the SDL
rover subgraph fetch my-graph@production --name products --format json | jq -r '.data.sdl'

# Check for errors
rover subgraph check my-graph@production --name products --schema ./schema.graphql --format json | jq '.error'
```

## Logging

### Log Levels

```bash
# Increase verbosity
rover --log debug subgraph fetch my-graph@production --name products

# Available levels: error, warn, info, debug, trace
```

### Environment Variable

```bash
export APOLLO_TELEMETRY_DISABLED=1  # Disable telemetry
export ROVER_LOG=debug              # Set log level
```

## Telemetry

Rover collects anonymous usage data by default.

### Disable Telemetry

```bash
export APOLLO_TELEMETRY_DISABLED=1
```

### What's Collected

- Command names (not arguments or schemas)
- Rover version
- OS type
- Anonymous usage patterns

## Proxy Configuration

### HTTP Proxy

```bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
```

### No Proxy

```bash
export NO_PROXY=localhost,127.0.0.1,.internal.example.com
```

## SSL/TLS Configuration

### Custom CA Certificate

```bash
# Set CA bundle
export SSL_CERT_FILE=/path/to/ca-bundle.crt

# Or for curl-based operations
export CURL_CA_BUNDLE=/path/to/ca-bundle.crt
```

### Disable SSL Verification (Not Recommended)

```bash
# For development only
export ROVER_SKIP_SSL_VALIDATION=1
```

## Updating Rover

### Check for Updates

```bash
rover update check
```

### Update to Latest

```bash
# npm
npm update -g @apollo/rover

# curl (reinstall)
curl -sSL https://rover.apollo.dev/nix/latest | sh
```

## Uninstalling

### npm

```bash
npm uninstall -g @apollo/rover
```

### Manual Installation

```bash
# Remove binary
rm -rf ~/.rover

# Remove from PATH (in .bashrc/.zshrc)
# Remove: export PATH="$HOME/.rover/bin:$PATH"
```

## Troubleshooting

### Authentication Issues

```bash
# Clear and re-authenticate
rm ~/.rover/config.toml
rover config auth
```

### Network Issues

```bash
# Test connectivity
curl -I https://api.apollographql.com

# Check DNS
nslookup api.apollographql.com
```

### Permission Issues

```bash
# Fix permissions (macOS/Linux)
chmod +x ~/.rover/bin/rover
```

### Version Conflicts

```bash
# Check installed location
which rover

# Ensure correct version
rover --version
```

```