EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
The Rover graph-artifact Command
Manage graph artifacts in Apollo's OCI distribution
This command requires authenticating Rover with GraphOS.
Apollo OCI distribution stores the graph artifacts (such as composed supergraph schemas) that GraphOS Router fetches at runtime. Each artifact is identified by a content-addressed digest, and you can assign human-readable tags to those artifacts so consumers can refer to them by name instead of by digest.
The rover graph-artifact set of commands lets you manage graph artifacts from the command line.
Tagging a graph artifact
graph-artifact tag
Use Rover to assign a tag to a graph artifact in your graph. Tagging an artifact enables GraphOS Router to fetch it by tag name instead of by digest, which makes it easier to promote a specific artifact across environments.
Run the graph-artifact tag command:
rover graph-artifact tag <TAG> --graph-id <GRAPH_ID> --digest <DIGEST>Alternatively, you can identify the artifact by its ID instead of its digest:
rover graph-artifact tag <TAG> --graph-id <GRAPH_ID> --graph-artifact-id <GRAPH_ARTIFACT_ID>The
--graph-id <GRAPH_ID>option is the ID of the graph that owns the artifact you want to tag.The
<TAG>argument is the name of the tag to assign to the artifact.You must provide exactly one of
--digestor--graph-artifact-idto identify the artifact you want to tag.
Removing a tag from a graph artifact
graph-artifact untag
Use Rover to remove a tag from your graph. Deleting a tag removes it and its full history. Tags managed by Apollo can't be deleted.
Run the graph-artifact untag command:
1rover graph-artifact untag <TAG> --graph-id <GRAPH_ID>The
--graph-id <GRAPH_ID>option is the ID of the graph that owns the tag you want to remove.The
<TAG>argument is the name of the tag to remove from the graph.
Fetching a graph artifact
graph-artifact fetch
Use rover graph-artifact fetch to fetch metadata about a graph artifact from Apollo's OCI distribution. This command returns an artifact's content-addressed digest, the launch that produced it, and (when fetching by tag) its assignment history.
Identify the artifact using one of the following mutually exclusive options:
By tag name (
--tag-name)By artifact ID (
--graph-artifact-id)By content-addressed digest (
--digest)
You must provide exactly one of --tag-name, --graph-artifact-id, or --digest.
Options
| Option | Description |
|---|---|
--graph-id | Required. The ID of the graph that owns the artifact. |
-t, --tag-name | Fetch by tag name. Mutually exclusive with --graph-artifact-id and --digest. |
-g, --graph-artifact-id | Fetch by artifact ID. Mutually exclusive with --tag-name and --digest. |
-d, --digest | Fetch by content-addressed digest. Mutually exclusive with --tag-name and --graph-artifact-id. |
--history-limit | When fetching by tag, the number of tag history entries to include (default: 5, max: 20). |
--format | Output format: plain (default) or json. |
Output
The command prints the following fields for the resolved artifact:
Graph ID – the ID of the graph
Artifact ID – the unique identifier for the artifact
Digest – the content-addressed hash of the artifact
Launch ID – the ID of the launch that produced the artifact
Tag – the tag name (only shown when fetching by tag)
Created at / Updated at – timestamps for when the artifact was created and last updated
When fetching by tag, the output also includes a history table showing recent tag reassignments. Each row lists the digest that was assigned and when the reassignment occurred. Use --history-limit to control how many entries are shown.
Errors
If the artifact cannot be resolved, the command exits with an error describing the cause:
Artifact not found – no artifact matches the given tag name, artifact ID, or digest.
Artifact is still being built – the artifact's build is pending. Wait for the launch to complete and retry.
Artifact failed to build – the artifact's build failed. Check the associated launch for details.