Rover client commands

client check

This command requires authenticating Rover with GraphOS.

Validating operations against your schema

The rover client check command validates every GraphQL operation in your client project against your graph's published schema in GraphOS. It scans for .graphql files, parses all operations and fragments, and reports any operations that are incompatible with the schema — so you can catch breaking schema changes before they reach production.

Usage

1rover client check [GRAPH_REF] [OPTIONS]

GRAPH_REF is a graph ref in graph@variant form. Always specify the variant explicitly; if you omit it, Rover defaults to current.

File discovery

Rover scans for .graphql files using the glob patterns you provide. Specify multiple --include patterns and optionally exclude paths with --exclude.

1rover client check my-graph@staging \
2  --include "src/**/*.graphql" \
3  --exclude "src/__generated__/**"

By default, Rover scans from the current working directory. Use --root-dir to scan from a different location:

1rover client check my-graph@staging \
2  --root-dir /path/to/client \
3  --include "**/*.graphql"

Operation requirements

All operations must have names. Rover rejects anonymous operations (for example, { user { name } }) with an error. Give every operation an explicit name:

1# Invalid — will error
2{ user { name } }
3
4# Valid
5query GetUser {
6  user { name }
7}

Fragment deduplication and conflicts

Rover automatically deduplicates fragments defined identically across multiple files. However, if two files define a fragment with the same name but different bodies, rover client check returns an error listing the conflicting fragment names. In this case, make each fragment name globally unique to avoid conflicts.

Options

Examples

All operations pass

1rover client check my-graph@current --include "src/**/*.graphql"

1Validated 3 operations (5 files scanned)

1{
2  "client_check": {
3    "graph_ref": "my-graph@current",
4    "files_scanned": 5,
5    "operations_sent": 3,
6    "failures": [],
7    "validation_results": []
8  }
9}

Validation failures

When an operation references a field that has been removed or renamed in the schema, rover client check reports a FAILURE for that operation and exits with code 1.

1rover client check my-graph@current --include "src/**/*.graphql"

1Validated 3 operations (5 files scanned)
2GetUser: src/queries/user.graphql:4:1
3  FAILURE Field "legacyId" was removed from type "User".

1{
2  "client_check": {
3    "graph_ref": "my-graph@current",
4    "files_scanned": 5,
5    "operations_sent": 3,
6    "failures": [],
7    "validation_results": [
8      {
9        "operation_name": "GetUser",
10        "type": "FAILURE",
11        "code": "FIELD_REMOVED",
12        "description": "Field \"legacyId\" was removed from type \"User\".",
13        "file": "src/queries/user.graphql",
14        "line": 4,
15        "column": 1
16      }
17    ]
18  }
19}

Parse errors

Files containing anonymous operations or invalid GraphQL syntax produce local parse errors. These are listed separately from schema validation results and always cause a non-zero exit.

1rover client check my-graph@current --include "src/**/*.graphql"

1Validated 2 operations (4 files scanned)
2Local parse errors:
3  src/queries/draft.graphql: Operation must have a name

Exclude generated files

Use --include and --exclude together to scan only the files you own.

1rover client check my-graph@staging \
2  --include "src/**/*.graphql" \
3  --exclude "src/__generated__/**"

Continuous integration

Run rover client check in your CI pipeline against the same variant you deploy to.

1- name: Validate client operations
2  run: |
3    rover client check my-graph@production \
4      --include "src/**/*.graphql"
5  env:
6    APOLLO_KEY: ${{ secrets.APOLLO_KEY }}

client extract

Extracting GraphQL from source files

The rover client extract command scans your source files for embedded GraphQL documents and writes each one to a standalone .graphql file. Use the extracted files with other Rover commands, code generation pipelines, or source control review.

Usage

1rover client extract [OPTIONS]

By default, Rover scans all supported file types (.ts, .tsx, .swift, .kt, and .kts) under the current working directory and writes extracted documents to a graphql/ directory.

Supported languages

For TypeScript, Rover recognizes both gql and graphql tags:

1const GET_USER = gql`
2  query GetUser($id: ID!) {
3    user(id: $id) { name }
4  }
5`;

File discovery

Use --include and --exclude to control which files are scanned. Patterns are evaluated as globs relative to --root-dir.

1rover client extract \
2  --include "src/**/*.ts" \
3  --exclude "src/__generated__/**"

Use --root-dir to scan from a location other than the current working directory:

1rover client extract \
2  --root-dir /path/to/client \
3  --out-dir graphql

To restrict extraction to specific languages, use --language. Accepted values are ts (scans .ts and .tsx), swift, or kotlin (scans .kt and .kts). Repeat --language to select multiple languages:

1rover client extract --language ts --language swift

Output directory

Rover writes extracted documents to --out-dir (default: graphql), preserving the relative path of each source file:

1src/components/UserCard.ts  →  graphql/src/components/UserCard.graphql

If a .graphql file already exists at the target path, Rover writes to <name>.generated.graphql instead. Pass --overwrite to replace existing files:

1rover client extract --out-dir graphql --overwrite

Skipped documents

Rover skips documents it cannot statically extract but always exits with code 0. Common skip reasons:

• Template interpolation — TypeScript documents containing ${...} expressions cannot be extracted

• GraphQL syntax error — the document could not be parsed as valid GraphQL

Each skipped document is listed in the output with its source path, line number, and reason.

Options

Examples

Basic extraction

1rover client extract --out-dir graphql

1Processed 12 source files; 4 contained GraphQL.
2Wrote 7 documents to /path/to/graphql

1{
2  "client_extract": {
3    "out_dir": "/path/to/graphql",
4    "source_files_processed": 12,
5    "source_files_with_graphql": 4,
6    "documents_extracted": 7,
7    "documents_skipped": 0,
8    "files": [
9      {
10        "source": "src/components/UserCard.ts",
11        "target": "graphql/src/components/UserCard.graphql",
12        "documents": 2
13      },
14      {
15        "source": "src/queries/user.ts",
16        "target": "graphql/src/queries/user.graphql",
17        "documents": 3
18      },
19      {
20        "source": "src/mutations/createPost.ts",
21        "target": "graphql/src/mutations/createPost.graphql",
22        "documents": 1
23      },
24      {
25        "source": "src/fragments/userFields.ts",
26        "target": "graphql/src/fragments/userFields.graphql",
27        "documents": 1
28      }
29    ],
30    "skipped": []
31  }
32}

TypeScript only

1rover client extract --language ts --out-dir graphql

1Processed 8 source files; 3 contained GraphQL.
2Wrote 5 documents to /path/to/graphql

Custom output directory

1rover client extract --out-dir dist/graphql

1Processed 12 source files; 4 contained GraphQL.
2Wrote 7 documents to /path/to/dist/graphql

Overwrite existing files

By default, if graphql/src/queries/user.graphql already exists, Rover writes to graphql/src/queries/user.generated.graphql instead. Pass --overwrite to replace the original file.

1rover client extract --out-dir graphql --overwrite

With skipped documents

Rover skips documents that contain template interpolations or GraphQL syntax errors and still exits with code 0.

1rover client extract --out-dir graphql

1Processed 12 source files; 4 contained GraphQL.
2Wrote 6 documents to /path/to/graphql
3Skipped documents:
4  /path/to/src/DynamicQuery.ts:14 contains a template interpolation (${...}); only static strings can be extracted

1{
2  "client_extract": {
3    "out_dir": "/path/to/graphql",
4    "source_files_processed": 12,
5    "source_files_with_graphql": 4,
6    "documents_extracted": 6,
7    "documents_skipped": 1,
8    "files": [
9      {
10        "source": "src/components/UserCard.ts",
11        "target": "graphql/src/components/UserCard.graphql",
12        "documents": 2
13      }
14    ],
15    "skipped": [
16      {
17        "source": "/path/to/src/DynamicQuery.ts",
18        "line": 14,
19        "reason": "contains a template interpolation (${...}); only static strings can be extracted"
20      }
21    ]
22  }
23}