repository·main·Indexed 19 days ago
https://github.com/apollographql/roverRover is a CLI tool for working with the Apollo GraphQL Registry, enabling users to manage federated graphs, validate schemas, and interact with Apollo Studio. The tool provides a suite of GitHub Actions for installing the CLI and executing commands such as subgraph check, subgraph lint, subgraph publish, and persisted-queries publish.
rover-std is a library providing common utilities that define the CLI style for Apollo Rover. It provides top-level exports that wrap standard CLI functionalities, allowing developers to maintain a consistent user experience across different Rover components.
Key capabilities include:
timber is a Rust crate used to define the output format for traces, events, and spans. It is designed to work with the env_logger, log, and/or tracing ecosystems to standardize how diagnostic information is presented.Sputnik is a Rust crate designed to help CLI developers collect anonymous usage data. It centers around the sputnik::Session struct, which captures metadata about a single command execution, such as the command name, arguments, machine ID, session ID, working directory hash, platform details (OS and CI status), and the CLI version.
To use Sputnik, you must implement the sputnik::Report trait. This trait allows you to define how the sputnik::Session is populated for every command and how that data is reported to your telemetry backend.
body:
command:
name: config list
arguments:
machine_id: edd890f0-3f8d-43f5-a22e-d3731d7e5042
session_id: a9d345b6-75f9-4bc1-9685-8475c6771610
cwd_hash: 52b120fee6f41776b6fb561ecb708cfe187e6922fa33a2399f8e01cb94e89bb0
platform:
os: macos
continuous_integration: null
cli_version: 0.0.0Rover includes a specialized connector command group designed for managing Apollo Connectors. These commands enable a workflow for:
For a full list of specific subcommands and flags, refer to the official CLI tools for connectors documentation.
The Rover repository is organized into several key areas:
src/: The main CLI executable.src/bin/rover.rs: CLI entry point.src/command/: Logic for CLI commands, organized by noun (e.g., src/command/graph/).src/cli.rs: Definition of top-level commands.src/lib.rs: Core CLI logic.src/error/: Application-level error handling.crates/: Workspace crates for shared logic:rover-client: Logic for querying Apollo services (GraphQL operations).rover-std: Standardized logging and behavior wrappers.houston: Configuration logic.timber: Output formatting and logging.installers/: Installation scripts for binstall and npm.tests/: Integration tests.When using rover schema describe, you can use the --coord option to inspect specific parts of the schema. The following coordinate patterns are supported:
Coordinate (--coord) | What you get |
|---|---|
| (none) | Schema overview |
Type | Type description |
Type.field | Field description and return type |
Type.field(arg:) | Field argument detail |
@directive | Directive definition detail |
@directive(arg:) | Directive argument detail |
rover schema describe schema.graphql --coord User.posts(limit:)When running check or publish commands, Rover sends non-confidential Git information (remote URL, commit SHA, committer, and branch name) to GraphOS to help track schema changes in the Studio UI.
To view this information locally, run the command with --log trace.
You can override these values using the following environment variables:
APOLLO_VCS_REMOTE_URLAPOLLO_VCS_BRANCHAPOLLO_VCS_COMMITAPOLLO_VCS_AUTHORRover uses specific terminology depending on whether you are working with monolithic or federated architectures:
When working with federation, most Rover commands are executed against a specific subgraph rather than the entire supergraph. supergraph commands are specifically used when interacting with supergraph schemas.
Action releases are pinned in lockstep with Rover releases. You can choose between two main versioning strategies:
@rover-v0.X.Y): This is the recommended approach. It runs the exact version of Rover specified (e.g., @rover-v0.39.1 runs Rover 0.39.1). Because both the action and Rover use immutable releases, this provides high reliability.@v1): This is a pre-lockstep version. It does not guarantee immutability and should only be used if you need an older version of Rover (pre-0.39.1) or if you do not wish to pin a specific version.The manifest generated by rover persisted-queries generate follows the Apollo persisted query manifest format. Each operation entry contains:
id: The SHA-256 hash of the operation's body.name: The operation name.type: The operation type (query, mutation, or subscription).body: The full GraphQL operation string.Example structure:
{
"format": "apollo-persisted-query-manifest",
"version": 1,
"operations": [
{
"id": "e5c9c9f2d1a0a9f4f6b6a1e2d3c4b5a6978869504132a1b2c3d4e5f60718293a",
"name": "GetProduct",
"type": "query",
"body": "query GetProduct($id: ID!) { ... }"
}
]
}{
"format": "apollo-persisted-query-manifest",
"version": 1,
"operations": [
{
"id": "e5c9c9f2d1a0a9f4f6b6a1e2d3c4b5a6978869504132a1b2c3d4e5f60718293a",
"name": "GetProduct",
"type": "query",
"body": "query GetProduct($id: ID!) {\n product(id: $id) {\n id\n name\n }\n}"
}
]
}When interacting with GraphOS, Rover requires a graph ref as the first positional argument. A graph ref identifies a specific variant of a graph using the following format:
graph_id@variant_name
Example: docs-example-graph@staging
graph_id@variant_name