# Architecture
Source: https://cosmo-docs.wundergraph.com/architecture
High-level architecture of the Cosmo Platform
![]()
The architecture of the Cosmo Platform is founded on several key principles.
We have constructed our platform based on open standards such as Open Telemetry (OTEL), S3, and Prometheus. The Router is fully Open-Source under the Apache 2.0 license. You can fully customize it, e.g., with custom modules.
We have designed all of our components with the intention of reducing downtime and preventing service loss. The Router is engineered to function independently, only having one dependency on the CDN to load its configuration, which guarantees an uptime of 99.999%.
We have meticulously selected our components to handle even the most demanding use cases. This enables us to efficiently handle billions of requests per month.
You have the option to run the entire platform on your own infrastructure, maintaining 100% data sovereignty. Alternatively, you can use [Cosmo Cloud](/deployments-and-hosting/cosmo-cloud) and only run the Router. We will operate the more complex, "stateful" components for you.
All components have been engineered to work together in the most efficient manner. Despite the potential limitations this might introduce, we view it as a strategic advantage. This holistic control over the entire stack not only enables us to optimize operations and costs but also significantly enhances the development experience.
### Cosmo Reference Architecture
Next, let's take a look at the Reference Architecture, which is also the blueprint of Cosmo Cloud.
![]()
The Cosmo Platform architecture comprises several integral components. The **Router** efficiently manages traffic and routes requests between clients and Subgraphs, relying solely on the **CDN** to load its configuration.
**Studio** provides a user-friendly interface for managing and monitoring services, validating Schema Checks, trying out Queries in the Playground, exploring the Schema or analyzing bottlenecks through metrics and distributed tracing.
User authentication and authorization are handled by **Keycloak,** making it easy to integrate with your own Identity Provider through OpenID Connect (OIDC) or SCIM.
The **Controlplane** manages the Graphs and their Schema, while the **OTEL Collector** aggregates telemetry data. The **GraphQL Metrics Collector** is responsible for gathering Schema usage information, which is essential to being able to provide composition checks against live traffic.
**PostgreSQL** and **Redis** serve as core databases for storing critical data, with **Clickhouse** used for high-performance analytical queries. Together, these components ensure a robust, efficient, and scalable platform.
# API Keys
Source: https://cosmo-docs.wundergraph.com/cli/api-keys
API Keys are required to perform any of the **wgc** CLI commands. To create an API key, follow the steps shown [here](/studio/api-keys).
### Usage
```bash theme={"system"}
export COSMO_API_KEY=
```
# Auth
Source: https://cosmo-docs.wundergraph.com/cli/auth
# Login
Source: https://cosmo-docs.wundergraph.com/cli/auth/login
Login a user into the Cosmo platform. Supports browser-based authentication.
## Usage
```bash theme={"system"}
npx wgc auth login
```
## Description
The `npx wgc auth login` command allows you to login as a user into the Cosmo platform. You will be prompted to select the organization if you are part of multiple organizations.
# Logout
Source: https://cosmo-docs.wundergraph.com/cli/auth/logout
Logout a user from the Cosmo platform.
## Usage
```bash theme={"system"}
npx wgc auth logout
```
## Description
The `npx wgc auth logout` command allows you to logout from the Cosmo platform.
# Whoami
Source: https://cosmo-docs.wundergraph.com/cli/auth/whoami
Displays the identity currently authenticated and in use.
## Usage
```bash theme={"system"}
npx wgc auth whoami
```
## Description
The `npx wgc auth whoami` command allows you to figure out who is currently authenticated with the controlplane. It displays the organization and controlplane URL.
### Options
* `-j, --json` : Output the information in JSON format.
# Clients
Source: https://cosmo-docs.wundergraph.com/cli/clients
Manage registered GraphQL clients for persisted operations
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/clients/delete
Delete a registered GraphQL client from a federated graph or monograph
## Usage
```bash theme={"system"}
npx wgc clients delete --graph-name
```
## Description
The `npx wgc clients delete` command deletes a registered GraphQL client from a federated graph or monograph.
If the client has persisted operations or persisted operation traffic, the command asks for confirmation. Confirming deletes the client and its related persisted operations.
Use `--force` to skip confirmation. Use `--json` to print structured JSON output.
## Parameters
* ``: The name of the registered GraphQL client.
## Options
* `-g, --graph-name ` : The name of the federated graph or monograph the client belongs to. Required.
* `-n, --namespace ` : The namespace of the federated graph or monograph. Defaults to `default`.
* `-j, --json` : Prints structured JSON instead of text.
* `-f, --force` : Deletes the client without confirmation. Required with `--json` if persisted operations would be deleted or have traffic.
## Examples
```bash theme={"system"}
npx wgc clients delete web --graph-name production
```
Deletes the client named `web` from the graph named `production`.
```bash theme={"system"}
npx wgc clients delete web --graph-name production --namespace staging --force
```
Deletes the client named `web` from the graph named `production` in the `staging` namespace without prompting.
```bash theme={"system"}
npx wgc clients delete web --graph-name production --json --force
```
Deletes the client named `web` and prints JSON output.
# List
Source: https://cosmo-docs.wundergraph.com/cli/clients/list
List registered GraphQL clients of a federated graph or monograph
## Usage
```bash theme={"system"}
npx wgc clients list
```
## Description
The `npx wgc clients list` command lists the registered GraphQL clients of a federated graph or monograph.
The table output includes the persisted operation count and whether the client has persisted operation traffic in the traffic retention window.
Clients are registered when persisted operations are pushed for a given client name.
## Parameters
* ``: The name of the federated graph or monograph.
## Options
* `-n, --namespace` : The namespace of the federated graph or monograph. Defaults to `default`.
* `-j, --json` : Prints structured JSON instead of a table.
## Examples
```bash theme={"system"}
npx wgc clients list production
```
Lists all registered clients of the graph named `production`.
```bash theme={"system"}
npx wgc clients list production --namespace staging --json
```
Lists all registered clients of the graph named `production` in the `staging` namespace and prints JSON output.
# Demo
Source: https://cosmo-docs.wundergraph.com/cli/demo
Run the interactive Cosmo demo that creates a local federated graph onboarding setup.
## Overview
`wgc demo` runs an interactive onboarding flow for a local Cosmo demo environment.
![Terminal running demo command]()
It is intended for first-time setup. The command prepares a demo federated graph, publishes the required demo plugins, creates a router token, and starts a local router so you can query the graph immediately.
```bash theme={"system"}
wgc demo
```
## Requirements
Before you run the command:
* Authenticate with the CLI.
* Use an organization account that is allowed to run onboarding. The command currently requires organization owner access.
* Install Docker and make sure the Docker daemon is running.
* Install Docker Buildx. If no `docker-container` builder exists, the command creates one automatically.
## What The Command Does
The command prepares a ready-to-use local demo setup for the onboarding flow. It creates or reuses a demo federated graph in the `default` namespace, configures the required demo components, starts a local router on `http://localhost:3002`, and leaves you with a working graph that you can query immediately. If a previous demo setup already exists, you can continue with it or delete it and start over. During execution, the command also prints the path to the local log file so you can inspect router and publishing output if needed.
## Notes
`wgc demo` is intentionally guided and uses predefined values. It is meant as a tutorial entry point, not as a general-purpose graph provisioning command.
For manual graph management, use the standard CLI commands such as [`wgc federated-graph`](/cli/federated-graph), [`wgc subgraph`](/cli/subgraph), and [`wgc router token`](/cli/router/token).
# Essentials
Source: https://cosmo-docs.wundergraph.com/cli/essentials
Please read through this to have a better understanding of the nuances that take place when executing commands which we will cover in the upcoming pages.
## Namespaces
Namespaces are the way to group and isolate graphs in different environments, such as production and staging. For example you can have a federated graph called `my-api` in a production and staging namespace. All graph operations and compositions are scoped to graphs present in a particular namespace. Every organization is provided a `default` namespace which cannot be deleted. You can create additional namespaces with the [namespace](/cli/namespace) CLI. Most of the CLI commands respect a `-n` flag or use `default` respectively. If you delete a namespace all resources within the namespace are deleted.
Namespaces have the following restrictions:
* Must begin and end with alphanumeric characters
* Could contain dashes (-) or underscores (\_) in between.
* Special characters other than the above mentioned are not allowed
Namespaces allow to create and organize multiple environments. Every federated graph represents physically a router instance and every subgraph is a service connected to the router.
## Monographs vs Federated Graphs
### Federated Graphs
Federated Graphs are the goto method of creating graphs in Cosmo. They compose multiple subgraphs into a unified Federated GraphQL schema.
### Monographs
Monographs are graphs that do not perform GraphQL Federation. They consist strictly of a single subgraph that is created internally for you. Monograph commands abstract away the complexities with interacting with that subgraph. Everything supported by Federated Graphs is also supported by Monographs.
## Order of execution
The order in which you create graphs does not matter. You can either create subgraphs first or federated graphs. Depending on the labels the appropriate subgraphs will be taken into account for composing your federated graphs.
## Labels
Labels are a `key=value` pair separated by a `=` sign. Ex: `team=A` `region=us-east-1`
You can assign labels to only subgraphs. Labels have the following restrictions
* Both key and value must be 63 characters or less (cannot be empty).
* Must begin and end with an alphanumeric character (\[a-z0-9A-Z]).
* Could contain dashes (-), underscores (\_), dots (.), and alphanumerics between.
## Label Matcher
Label matchers are used with Federated Graphs to determine which subgraphs are chosen for composition. They are a set of labels separated by spaces (or the option) and grouped by commas.
To understand how they work here is an example.
You can create subgraphs and federated graphs without labels and label matchers. In such a case, federated graphs with empty label matchers will only compose subgraphs with empty labels. The vice versa is also true, subgraphs without labels can only be composed by federated graphs with empty label matchers.
#### Federated Graph example
We create a federated graph from all subgraphs that match the label `Team A` or `Team B` and `Region us-east-1`. This can be expressed in the following way:
`--label-matcher team=A,team=B region=us-east-1`
the long version is
`--label-matcher team=A,team=B --label-matcher region=us-east-1`
The above *matcher* translates to logically to `(team=A || team=B) && region=us-east-1`
#### Subgraphs example:
Assuming we have the following subgraphs:
1\. Products `--label team=A region=us-east-1`
2\. Employees `--label team=B region=us-east-1`
3\. Hobbies `--label team=A`
4\. Users `--label region=us-east-1`
Based on the matcher above, this setup will create a federated graph consisting of subgraphs *Products* and *Employees*. *Hobbies* is excluded because it has no `region` label, and *Users* is excluded because it has no `team` label.
## Validate composition
While labeling is a powerful concept it can be very error-prone to understand the final result of your composition. For those reasons, we provide the CLI commands
* [`wgc federated-graph check`](/cli/federated-graph/check) and
* [`wgc subgraph check`](/cli/subgraph/check)
That allows you to validate if the composition will produce any errors and what the result will look like at the end.
## Routing Url
The routing Url must be specified when creating a federated graph or subgraph. In the case of a federated graph, it points to the Url of your Cosmo router. For subgraphs, it is the service URL that the subgraph will be accessible at.
# Feature Flags
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags
An overview of feature-flag (alias "ff") commands.
A feature flag is a group of one or more [feature subgraphs](/cli/feature-subgraph). Each feature subgraph represents a replacement of a specific base subgraph that composes a federated graph. Feature flags define labels that dictate the federated graphs to which they will apply when enabled. Setting the corresponding feature-flag header or cookie value allows different graph constellations to be served to clients.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
# Create Feature Flag
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags/create-feature-flag
How to create a feature flag.
## Description
Create a new feature flag within the specified namespace (or the "default" namespace if unspecified). A feature flag is a group of one or more [feature subgraphs](/cli/feature-subgraph). Each feature subgraph represents a replacement of a specific base subgraph that composes a federated graph.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
A feature flag is disabled when created by default. To create and immediately enable a feature flag, include the `--enabled` flag. To enable after creation, see [`wgc ff enable`](/cli/feature-flags/enable-feature-flag).
```bash theme={"system"}
wgc feature-flag create my-flag --feature-subgraphs my-graph-one my-graph-two
```
The alias for `feature-flag` is `ff`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
If either the base composition (the Federated Graph with the original Subgraphs) or the Feature Flag composition fail, the Router Config will not be updated with the Feature Flag configuration.
## Parameters
* ``: The name of the Feature Flag to create. Must be unique among all feature flags in the specified (otherwise "default") namespace.
## Required Options
`--fs, --feature-subgraphs:` A list of names of the feature subgraphs that compose the feature flag. At least one feature subgraph name must be included, and multiple names are space delimited. Including a non-feature subgraph or a feature subgraph that does not exist in the specified (otherwise "default") namespace will produce an error.
## Options
* `-n, --namespace` : The namespace of the feature flag (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
* `-e --enabled`: Activates the feature flag immediately upon creation. A new feature flag is disabled by default to prevent accidental compositions.
* `--label [labels...]:`The labels to apply to the feature flag. The labels are passed in the format `key=value`, and multiple values are space delimited.
* `-j, --json` : Outputs the information in JSON format.
## Example
Create the feature flag "my-flag" in the namespace "prod" with multiple feature subgraphs and the labels `team=A` and `team=B`:
```bash theme={"system"}
wgc feature-flag create my-flag \
--feature-subgraphs my-graph my-other-graph \
-n prod
--label team=A team=B
```
# Delete Feature Flag
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags/delete-feature-flag
How to delete a feature flag
## Description
Deletes an existing feature flag within the specified namespace (or the "default" namespace if unspecified).
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
If a feature flag is deleted, the feature subgraphs part of the feature flag is not deleted.
```bash theme={"system"}
wgc feature-flag delete my-flag
```
The alias for `feature-flag` is `ff`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
## Parameters
* ``: The name of the feature flag to delete. Returns an error if the feature flag does not exist in the specified (otherwise "default") namespace.
## Options
* `-n, --namespace` : The namespace of the feature flag (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
* `-f, --force`: An optional flag that allows you to force delete the feature flag without being prompted for confirmation. Use this option if you want to delete the feature flag without additional prompts.
## Examples
Enable the existing feature flag "my-flag" in the namespace "prod":
```bash theme={"system"}
wgc feature-flag delete my-flag -n prod
```
# Disable Feature Flag
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags/disable-feature-flag
How to disable a feature flag.
## Description
Disable (deactivate) an existing feature flag within the specified namespace (or the "default" namespace if unspecified). A feature flag is a group of one or more [feature subgraphs](/cli/feature-subgraph). Each feature subgraph represents a replacement of a specific base subgraph that composes a federated graph.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
If `feature-flag disable` is used when the feature flag is already disabled, no changes (nor errors) will occur.
```bash theme={"system"}
wgc feature-flag disable my-flag
```
The alias for `feature-flag` is `ff`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
## Parameters
* ``: The name of the feature flag to disable. Returns an error if the feature flag does not exist in the specified (otherwise "default") namespace.
## Options
* `-n, --namespace` : The namespace of the feature flag (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
## Examples
Enable the existing feature flag "my-flag" in the namespace "prod":
```bash theme={"system"}
wgc feature-flag disable my-flag -n prod
```
# Enable Feature Flag
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags/enable-feature-flag
How to enable a feature flag.
## Description
Enable (activate) an existing feature flag within the specified namespace (or the "default" namespace if unspecified). A feature flag is a group of one or more [feature subgraphs](/cli/feature-subgraph). Each feature subgraph represents a replacement of a specific base subgraph that composes a federated graph.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
If `feature-flag enable` is used when the feature flag is already enabled, no changes (nor errors) will occur.
```bash theme={"system"}
wgc feature-flag enable my-flag
```
The alias for `feature-flag` is `ff`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
If either the base composition (the federated graph with the original subgraphs) or the feature flag composition fail, the router execution config will not be updated with the feature flag configuration.
## Parameters
* ``: The name of the feature flag to enable. Returns an error if the feature flag does not exist in the specified (otherwise "default") namespace.
## Options
* `-n, --namespace` : The namespace of the feature flag (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
## Examples
Enable the existing feature flag "my-flag" in the namespace "prod":
```bash theme={"system"}
wgc feature-flag enable my-flag -n prod
```
# Update Feature Flag
Source: https://cosmo-docs.wundergraph.com/cli/feature-flags/update-feature-flag
How to update a feature flag.
## Description
Update an existing feature flag within the specified namespace (or the "default" namespace if unspecified). A feature flag is a group of one or more [feature subgraphs](/cli/feature-subgraph). Each feature subgraph represents a replacement of a specific base subgraph that composes a federated graph.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
```bash theme={"system"}
wgc feature-flag update my-flag --feature-subgraphs fs1 fs2
```
The alias for `feature-flag` is `ff`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
If either the base composition (the federated graph with the original subgraphs) or the feature flag composition fail, the router execution configuration will not be updated with the feature flag configuration.
## Parameters
* ``: The name of the existing feature flag to update. Returns an error if the feature flag does not exist in the specified (otherwise "default") namespace.
## Options
* `--fs, --feature-subgraphs:` A list of names of the feature subgraphs that compose the feature flag. At least one feature subgraph name must be included, and multiple names are space delimited. Including a non-feature subgraph or a feature subgraph that does not exist in the specified (otherwise "default") namespace will produce an error. Including this option will overwrite the existing list.
* `-n, --namespace` : The namespace of the feature flag (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
* `--label [labels...]:`The labels to apply to the feature flag. The labels are passed in the format `key=value`, and multiple values are space delimited. Including this option will overwrite the existing list.
* `--unsetlabels:` Removes all existing labels. If the `--label` parameter is also provided, it will be ignored.
* `-j, --json` : Output the information in JSON format.
## Example
Update the existing feature flag "my-flag" in the namespace "prod" with multiple feature subgraphs and the labels `team=A` and `team=B`:
```bash theme={"system"}
wgc feature-flag update my-flag \
--feature-subgraphs my-graph my-other-graph \
-n prod
--label team=A team=B
```
# Feature Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/feature-subgraph
An overview of feature-subgraph (alias "fs") commands.
Federated graphs are composed of "base subgraphs". Feature subgraphs represent a replacement (or "override") for a specific base subgraph. A feature subgraph exists only as long as its base subgraph also exists.
Creating a feature subgraph does nothing in isolation. It must be added to an enabled [feature flag](/concepts/feature-flags) to be considered by composition.
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
# Create Feature Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/feature-subgraph/create-feature-subgraph
How to create a feature subgraph.
## Description
Create a feature subgraph based on an existing subgraph for your federated graph within the specified (otherwise "default") namespace. A feature subgraph is an "override" of an existing subgraph. One or more feature subgraphs are used to compose a [feature flag](/cli/feature-flags).
## Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.58.0](https://github.com/wundergraph/cosmo/compare/wgc@0.57.7...wgc@0.58.0) |
| [router](/router/intro) | [0.95.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.95.0) |
## Usage
A feature subgraph does not function in isolation. One or more feature subgraphs must compose a [feature flag](/cli/feature-flags), which itself must be enabled to take effect.
```bash theme={"system"}
wgc feature-subgraph create my-feature-subgraph --subgraph my-subgraph --routing-url http://localhost:4000
```
The alias for `feature-subgraph` is `fs`.
Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
The type of the feature subgraph is determined by the type of the base subgraph. For example, if the base subgraph is a plugin subgraph, the feature subgraph will also be a plugin subgraph.
## Parameters
* ``: The name of the feature subgraph to create. Must be unique among all subgraphs and feature subgraphs within the specified (otherwise "default") namespace.
## Required Options
If the base subgraph does not exist in the specified (otherwise "default") namespace, the command will fail.
`--subgraph`: The name of the existing base subgraph for which the feature subgraph is to be created.
## Options
Feature subgraphs do not use labels directly; labels are set by the [feature flag](/cli/feature-flags) that the feature subgraph(s) compose.
If the base subgraph is not a plugin subgraph, the routing url is required.
* `-r , --routing-url`: Set the URL for the subgraph's data source. This URL defines the endpoint from which the subgraph will fetch data.
* `-n, --namespace` : The namespace of the feature subgraph (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
* `--subscription-url:` Use a different URL for subscription requests. If no subscription URL is provided, the router URL is used for subscriptions.
* `--subscription-protocol:` Set a protocol to use for subscriptions. The available options are:
* `ws` (default): Negotiate an appropriate protocol over websockets. Both `graphql-ws` and `subscription-transport-ws` are supported.
* `sse`: Use Server-Sent Events with a GET request.
* `sse_post`: Use Server-Sent events with a POST request.
## Examples
* Create the feature subgraph "my-feature-subgraph" based on the existing subgraph "my-subgraph" in the namespace "prod".
```bash theme={"system"}
wgc feature-subgraph create my-feature-subgraph \
--subgraph my-subgraph \
--namespace prod \
--routing-url http://localhost:4000
```
# Delete Feature Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/feature-subgraph/delete-feature-subgraph
How to delete a feature subgraph
## Description
Delete a feature subgraph within the specified (otherwise "default") namespace. A feature subgraph is an "override" of an existing subgraph.
## Usage
The command to delete the feature subgraph is the same as the subgraph. Please refer to [subgraph delete](/cli/subgraph/delete).
# Publish Feature Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/feature-subgraph/publish-feature-subgraph
How to publish a feature subgraph.
## Description
Publish a feature subgraph within the specified (otherwise "default") namespace. A feature subgraph is an "override" of an existing subgraph.
## Usage
The command to publish the feature subgraph is the same as the subgraph. Please refer to [subgraph publish](/cli/subgraph/publish).
# Update Feature Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/feature-subgraph/update-feature-subgraph
How to update a feature subgraph
## Description
Update a feature subgraph within the specified (otherwise "default") namespace. A feature subgraph is an "override" of an existing subgraph.
## Usage
The command to update the feature subgraph is the same as the subgraph. Please refer to [subgraph update](/cli/subgraph/update).
Feature subgraph labels cannot be changed. Feature subgraph labels are determined by the feature flag they compose.
# Federated Graph
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph
A federated graph refers to a single, unified data graph that is composed of multiple subgraphs.
Before you can interact with a federated graph, you need to [`create`](/cli/federated-graph/create) it. Each federated graph is mapped to a [Cosmo Router](/router/intro) service that can respond to the relevant GraphQL schema.
# Changelog
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/changelog
Retrieves the changelog for a federated graph
## Usage
```bash theme={"system"}
npx wgc federated-graph changelog
```
## Description
The `npx wgc federated-graph changelog` command allows you to retrieve the changelog for a given federated graph. By default it fetches the latest 10 schema versions from the past 3 days and writes to changelog.json file.
## Parameters
* ``: The name of the federated graph you want to create. Replace `` with the desired name for your federated graph.
## Options
`-n, --namespace` : The namespace of the federated graph (Default: "default").
`-l, --limit`: The number of entries to fetch. Defaults to 10.
`-f, --offset`: Used for pagination. Sets the offset from which you want to query.
`-s, --start`: The start date in `MM-DD-YY` format. Defaults to 3 days ago from current date.
`-e, --end`: The end date in `MM-DD-YY` format. Defaults to today.
`-o, --out`: The destination file for the json output. Defaults to `changelog.json`
## Examples
```bash theme={"system"}
npx wgc federated-graph changelog production -s 08-15-23 -e 08-31-23 -o changes.json
```
Fetch first 10 changes from 8th August to 31st August for the graph `production` and write it to `changes.json` file.
```bash theme={"system"}
npx wgc federated-graph changelog production -s 08-15-23 -e 08-31-23 -l 10 -f 10 -o changes.json
```
Fetch the next 10 changes (after the ones in the previous example) from 8th August to 31st August for the graph `production` and write it to `changes.json` file.
## Sample output
```json theme={"system"}
[
{
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)",
"schemaVersionId": "4f46116d-b307-4bf4-8d24-1974e794819d",
"changelogs": [
{
"id": "2b1db820-6f93-42ac-80a2-b0f5a8d765f3",
"path": "ProductNames",
"changeType": "TYPE_ADDED",
"changeMessage": "Type 'ProductNames' was added",
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)"
},
{
"id": "0aaf1f49-2fb9-4528-85e4-f4b4b3c671ae",
"path": "Employee.products",
"changeType": "FIELD_ADDED",
"changeMessage": "Field 'products' was added to object type 'Employee'",
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)"
}
]
},
..more versions
]
```
# Check
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/check
Checks for composition errors and presents a list of subgraphs that constitute the new federated graph.
## Usage
```bash theme={"system"}
npx wgc federated-graph check --label-matcher
```
## Description
The `npx wgc federated-graph check` command allows you to check for composition errors for the new labels provided. The subgraphs which match the labels will be federated and the errors, if they exist will be displayed to the user. This check can be performed without updating the labels of the federated graph.
## Parameters
* ``: The name of the federated graph you want to check for composition errors. Replace `` with the name of the federated graph.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `--label-matcher ` : The label matchers to the federated graph with which the check is to be performed
The labels used to select the subgraphs to be federated. Labels are passed in the format `= =`, where each `=` pair represents a label key and its corresponding value. The federated graph will include the subgraphs that match the updated labels.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
```bash theme={"system"}
npx wgc federated-graph check production --label-matcher team=B department=Engineering
```
Checks the federated graph named "production" for composition errors by composing the subgraphs that match the labels "team=B" or "department=Engineering".
```bash theme={"system"}
npx wgc federated-graph check production --label-matcher team=B --label-matcher department=Engineering
```
Checks the federated graph named "production" for composition errors by composing the subgraphs that match the labels "team=B" and "department=Engineering".
# Create
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/create
Creates a federated graph on the control plane.
## Usage
```bash theme={"system"}
npx wgc federated-graph create -r --label-matcher
```
## Description
The `npx wgc federated-graph create` command allows you to create a new federated graph on the Cosmo platform's control plane. Federated graphs provide a mechanism to combine multiple subgraphs into a unified schema, enabling efficient, scalable, and distributed GraphQL APIs. With this command, you can create a federated graph and specify the routing URL for your router and the labels used to select the subgraphs to be federated.
## Parameters
* ``: The name of the federated graph you want to create. Replace `` with the desired name for your federated graph.
## Required Options
`-r , --routing-url`: The routing URL of your router. This URL defines the endpoint where the router will be accessible. The federated graph will be accessible through this router.
`--label-matcher `: The labels used to select the subgraphs to be federated. Labels are passed in the format `= =`, where each `=` pair represents a label key and its corresponding value. The federated graph will include the subgraphs that match the specified labels.
`--readme`: The path to the markdown file which describes the federated graph. The readme can be used to communicate the information of the federated graph to other team members.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-r, --routing-url` :The routing url of your router. This is the url that the router will be accessible at.
* `--admission-webhook-url ` the base url of the admission webhook. This is the url that the controlplane will use to implement admission control for the federated graph. Example: `https://admission.example.com` (without the `/validate-config` path name)
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url. The header containing this signature is `X-Cosmo-Signature-256`
* `--label-matcher [labels...]` : The label matcher is used to select the subgraphs to federate. The labels are passed in the format = =. They are separated by spaces and grouped using comma. Example: --label-matcher team=A,team=B env=prod
* `--readme` : The markdown file which describes the federated graph.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
```bash theme={"system"}
npx wgc federated-graph create production -r http://router.example.com/graphql --label-matcher team=A department=backend
```
Create a federated graph named "production" with a routing URL of "[http://router.example.com/graphql](http://router.example.com/graphql)" and federate subgraphs with labels `team=A` and `department=backend`.
## Notes
* The `npx wgc federated-graph create` command interacts with the Cosmo platform's control plane to create the specified federated graph.
* The routing URL of the router should be accessible by the federated graph to handle incoming queries and route them to the appropriate subgraphs.
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/delete
Deletes a federated graph on the control plane.
## Usage
```bash theme={"system"}
npx wgc federated-graph delete [-f, --force]
```
**Delete** is an irreversible action. It will delete the entire federated graph, including versions, schema checks, etc. It will not delete the associated subgraphs.
Contract Graph behavior: Deleting a federated grpah will delete all associated contract graphs. Deleting a contract graph has no effect on the source federated graph.
## Description
The `npx wgc federated-graph delete` command allows you to delete a federated graph on the Cosmo platform's control plane. Deleting a federated graph will remove its configuration and associated resources. Use this command with caution, as the action cannot be undone.
## Parameters
* ``: The name of the federated graph you want to delete. Replace `` with the name of the federated graph you wish to remove.
## Options
`-n, --namespace` : The namespace of the federated graph (Default: "default").
```bash theme={"system"}
-f, --force
```
An optional flag that allows you to force delete the federated graph without being prompted for confirmation. Use this option if you want to delete the federated graph without additional prompts.
## Examples
```bash theme={"system"}
npx wgc federated-graph delete production
```
Delete the federated graph named "production".
```bash theme={"system"}
npx wgc federated-graph delete production -f
```
Force delete the federated graph named "production" without confirmation.
## Notes
* The `npx wgc federated-graph delete` command interacts with the Cosmo platform's control plane to delete the specified federated graph. Ensure that you have the necessary permissions to perform this operation.
* When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental deletions.
# Fetch
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/fetch
Fetches the latest valid SDL of a federated graph and all its subgraphs and the latest valid router config of a federated graph.
## Usage
```bash theme={"system"}
npx wgc federated-graph fetch
```
## Description
The `npx wgc federated-graph fetch` command allows you to download the latest valid Schema Definition Language (SDL) of a federated graph and all its subgraphs and the latest valid router config of a federated graph from the Cosmo platform's control plane. The fetched SDL represents the unified schema of the federated graph. You can use this command to retrieve the SDL.
## Parameters
* ``: The name of the federated graph you want to fetch. Replace `` with the name of the federated graph you wish to retrieve the SDL for.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-o, --out` : Destination folder for the SDL of the federated graph and its subgraphs.
* `-a, --apollo-compatibility` : Enable Apollo compatibility to generate the composition configs and script to generate schema using rover.
* `-v, --federation-version`: The version of federation to be used by rover in the format "1", "2", or "2.x.y". Default is 2.5.0.
## Apollo Compatibility
This mode will help smooth migration from the Apollo router to the WunderGraph Cosmo router. Initially, the users can use the schema registry from Cosmo and use this mode to update their routers/gateways. Later they can move from Apollo Router/Gateway to WunderGraph Router.
![Diagram showing Cosmo Schema Registry and WGC CLI generating an Apollo-compatible supergraph for the Apollo Router/Gateway, updated via webhook on schema change.]( "Apollo compatibility — Cosmo with Apollo Router/Gateway")
## Output
The output of this command is stored in the structure mentioned below
* **\-\: **The top-level folder which contains 2 folders, subgraphs and supergraphs.
* **subgraphs** folder: This folder contains the files of all the subgraph's SDLs.
* **supergraph** folder: This folder contains the SDL, router config of the federated graph.
* cosmoSchema.graphql - The SDL of the federated graph.
* cosmoConfig.json - The router config of the federated graph.
* **cosmo-composition.yaml: **The Cosmo federated graph configuration file includes configuration options for each of your subgraphs. This file can be used to generate the router config using the [compose](/cli/router/compose) command.
If **Apollo-compatibility mode** is enabled, the output will contain a few more folders/files, they are as follows:-
* **rover-composition.yaml: **The Apollo supergraph configuration file includes configuration options for each of your subgraphs.
* **scripts **folder
* apollo.sh - This script is used to generate the supergraph schema using rover, and the generated file would be in the **supergraph** folder and the name of the file would be '**apolloSchema.graphql**'.
## Examples
```bash theme={"system"}
npx wgc federated-graph fetch production
```
Fetches the latest valid SDL and router config of the federated graph named "production" and SDL of all its subgraphs.
```bash theme={"system"}
npx wgc federated-graph fetch production --apollo-compatibility -v 2.6.1
```
Fetches the latest valid SDL and router config of the federated graph named "production" and SDL of all its subgraphs. As Apollo compatibility mode is enabled, it generates the extra files mentioned above. Using the `-v` option, pass the version of the federation used by the rover, if not provided it falls back to "2.5.0".
# Fetch-Schema
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/fetch-schema
Fetches the latest valid SDL of a federated graph. The output can be piped to a file. This is primarily used for debugging purposes
## Usage
```bash theme={"system"}
npx wgc federated-graph fetch-schema
```
## Description
The `npx wgc federated-graph fetch-schema` command allows you to fetch the latest valid Schema Definition Language (SDL) of a federated graph from the Cosmo platform's control plane. You can use this command to retrieve the SDL and, if needed, pipe the output to a file.
By default, the output schema is set to the **Router Schema**. To use the **Client Schema** instead, specify the `-c` or `--client-schema` flag to the command.
## Parameters
* ``: The name of the federated graph you want to fetch. Replace `` with the name of the federated graph you wish to retrieve the SDL for.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-o, --out` : Destination file for the SDL. Prints to standard output if not provided.
* `-c, --client-schema`: Output the Client Schema instead of the default Router Schema.
## Examples
```bash theme={"system"}
npx wgc federated-graph fetch-schema production
```
Fetch the latest valid SDL of the federated graph named "production."
```bash theme={"system"}
npx wgc federated-graph fetch-schema production -o production-schema.graphql
```
Fetch the latest valid SDL of the federated graph named "production" and save it to a file named "production-schema.graphql."
```bash theme={"system"}
npx wgc federated-graph fetch-schema production --client-schema
```
Fetch the latest valid client SDL of the federated graph named "production".
## Notes
* The `npx wgc federated-graph fetch-schema` command interacts with the Cosmo platform's control plane to fetch the latest valid SDL of the specified federated graph. Ensure that you have the necessary permissions to perform this operation.
# List
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/list
Lists all the federated graphs.
## Usage
```bash theme={"system"}
npx wgc federated-graph list
```
## Description
The `npx wgc federated-graph list` command allows you to list all the federated graphs under your organization.
## Options
* `-n, --namespace` : Filter to get graphs in this namespace only.
* `-r, --raw` : Prints to the console in json format instead of table (Deprecated).
* `-j, --json` : Prints to the console in json format instead of table.
* `-o, --out` : Destination file for the json output. Has precedence over both `raw` and `json`
* `--only-contracts` : Filter to list only contracts
# Move
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/move
## Usage
```bash theme={"system"}
npx wgc federated-graph move -n fromNS -t toNS
```
Moving a federated graph will result in a new graph composition but only subgraphs from the target namespace are respected.
## Description
The `npx wgc federated-graph move` command allows you to move a federated-graph into a different namespace.
## Parameters
* ``: The name of the federated-graph you want to move.
## Options
* `-n, --namespace` : The namespace of the federated-graph.
* `-t, --to`: The new namespace of the federated-graph.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
* Moves the federated-graph named "mygraph" into the "production" namespace.
```bash theme={"system"}
npx wgc subgraph move mygraph -n default -t production
```
# Update
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/update
Updates a federated graph on the control plane.
## Usage
```bash theme={"system"}
npx wgc federated-graph update [-r, --routing-url ] [--label-matcher ] [--readme ]
```
**Update** is an irreversible action. However, the change will only be visible to the routers once the composition has been successful. Until then, the routers will operate with the most recent valid composition. Please use [federated-graph check](/cli/federated-graph/check) to understand the impact of your change.
## Description
The `npx wgc federated-graph update` command allows you to update an existing federated graph on the Cosmo platform's control plane. With this command, you can modify the routing URL of your router and update the labels used to select the subgraphs to be federated.
## Parameters
* ``: The name of the federated graph you want to update. Replace `` with the name of the federated graph you wish to modify.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-r , --routing-url` : The updated routing URL of your router. This URL defines the endpoint where the router will be accessible. The federated graph will be accessible through this updated router URL.
* `--label-matcher `: The updated labels used to select the subgraphs to be federated. Labels are passed in the format `= =`, where each `=` pair represents a label key and its corresponding value. The federated graph will include the subgraphs that match the updated labels.
* `--unset-label-matcher`: This will remove all label matchers. It will not add new label matchers if both this and --label-matchers option is passed.
* `--admission-webhook-url ` the base url of the admission webhook. This is the url that the controlplane will use to implement admission control for the federated graph. Example: `https://admission.example.com` (without the `/validate-config` path name)
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url. The header containing this signature is `X-Cosmo-Signature-256`
* `--readme ` : The path to the markdown file which describes the federated graph. The readme can be used to communicate the information of the federated graph to other team members.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
```bash theme={"system"}
npx wgc federated-graph update production -r http://new-router.example.com/graphql --selector team=B department=Engineering
```
Update the federated graph named "production" with an updated routing URL of "[http://new-router.example.com/graphql](http://new-router.example.com/graphql)" and update the labels to select subgraphs with "team=B" and "department=Engineering".
## Notes
* The `npx wgc federated-graph update` command interacts with the Cosmo platform's control plane to update the specified federated graph. Ensure that you have the necessary permissions to perform this operation.
* If you want to update both the routing URL and labels, you can combine the options in a single command as demonstrated in the examples.
# Version
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/version
# Get
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/version/get
Retrieves and displays the router compatibility version that has been set for a specific federated graph.
## Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.74.0](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.74.0) |
## Usage
```bash theme={"system"}
npx wgc federated-graph version get
```
## Description
The `wgc federated-graph version get` command retrieves and displays the router compatibility version that has been set for a specific federated graph.
## Output
The router compatibility version that has been set for the federated graph.
## Example
```bash theme={"system"}
> npx wgc federated-graph version get mygraph -n prod
┌────────────┬───────────┬─────────┐
│ GRAPH NAME │ NAMESPACE │ VERSION │
├────────────┼───────────┼─────────┤
│ mygraph │ prod │ 1 │
└────────────┴───────────┴─────────┘
```
# Set
Source: https://cosmo-docs.wundergraph.com/cli/federated-graph/version/set
Sets the router compatibility version for a federated graph.
Currently, there is only one router compatibility version. Consequently, this command does not yet serve a meaningful function (but will in the near future).
## Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.74.0](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.74.0) |
## Usage
```bash theme={"system"}
npx wgc federated-graph version set --version
```
## Arguments
| Description | Type |
| - | - |
| The name of the federated graph. | string |
## Options
| Option | Type | Value | Required | Default value |
| - | - | - | - | - |
| `--version/-v` | string | The router compatibility version to be set. | true | n/a |
| `--namespace/-n` | string | The namespace where the federated graph exists. | false | "default" |
## Description
The `wgc federated-graph version set` command allows a [valid router compatibility version](/cli/router/compatibility-version/list) to be set for a federated graph.
## Output
If successful, a table will display the graph name, its namespace, the previous router compatibility version, and the current router compatibility version.
## Example
```bash theme={"system"}
npx wgc federated-graph version set mygraph -v 1
✔ Successfully set the router compatibility version for federated graph "prod" to 1.
┌────────────┬───────────┬──────────────────┬─────────────┐
│ GRAPH NAME │ NAMESPACE │ PREVIOUS VERSION │ NEW VERSION │
├────────────┼───────────┼──────────────────┼─────────────┤
│ prod │ default │ 2 │ 1 │
└────────────┴───────────┴──────────────────┴─────────────┘
```
# gRPC Services
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service
Commands for working with gRPC services for the Cosmo Router
WunderGraph Cosmo CLI includes commands for working with gRPC services for the Cosmo Router.
Scaffold a new gRPC service project from a template
List all available gRPC service templates for the init command
Generate a protobuf definition and mapping file for a gRPC service from a
GraphQL schema
Create a federated gRPC subgraph on the control plane
Publish a gRPC subgraph schema to the control plane
Delete a gRPC subgraph from the control plane
For detailed documentation about gRPC services and how they work, see the [Router gRPC Services](/router/gRPC/grpc-services) documentation.
# Create
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/create
Creates a federated gRPC subgraph on the control plane.
## Usage
A gRPC subgraph name must be unique within a namespace.
```bash theme={"system"}
wgc grpc-service create -r [options]
```
After creating a gRPC subgraph, you can publish it with [wgc grpc-service
publish](/cli/grpc-service/publish).
## Description
The `wgc grpc-service create` command allows you to create a new gRPC subgraph within the Cosmo platform. The `` argument specifies the name of the new gRPC subgraph. This establishes the subgraph metadata and routing configuration without publishing any schema.
## Parameters
* ``: The name of the gRPC subgraph you want to create. It is used to uniquely identify your gRPC subgraph.
## Options
* `-r, --routing-url `: The routing URL of your subgraph. This is the gRPC endpoint where requests will be directed, and must follow the format from the gRPC protocol ([https://grpc.github.io/grpc/core/md\_doc\_naming.html](https://grpc.github.io/grpc/core/md_doc_naming.html)).
* `-n, --namespace [string]`: The namespace of the gRPC subgraph (Default: "default").
* `--label [labels...]`: Assign multiple labels to the new gRPC subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project). The labels are passed in the format `=`.
* Example: `--label team=backend`
* `--readme `: The path to the markdown file which describes the gRPC subgraph.
## Examples
* Create a new gRPC subgraph named "users-service" with a routing URL:
```bash theme={"system"}
wgc grpc-service create users-service -r dns:///localhost:4001/
```
* Create a new gRPC subgraph with labels:
```bash theme={"system"}
wgc grpc-service create users-service -r dns:///localhost:4001/ --label team=backend
```
* Create a new gRPC subgraph with a readme file:
```bash theme={"system"}
wgc grpc-service create users-service -r dns:///localhost:4001/ --readme ./service-readme.md
```
* Create a gRPC subgraph in a specific namespace:
```bash theme={"system"}
wgc grpc-service create users-service -r dns:///localhost:4001/ --namespace production
```
## Notes
* The `wgc grpc-service create` command interacts with the Cosmo platform's control plane to create the specified gRPC subgraph.
* The routing URL must be accessible from your router instances when you later publish the subgraph schema.
* The readme file will be displayed in the Studio for documentation purposes.
* After creating the subgraph, you'll need to use `wgc grpc-service publish` to publish your schema.
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/delete
Deletes a gRPC subgraph on the control plane. The gRPC subgraph will be deleted from all federated graphs.
## Usage
```bash theme={"system"}
wgc grpc-service delete [-f, --force]
```
**Delete** is an irreversible action. However, the change will only be visible
to the routers once the composition has been successful. Until then, the
routers will operate with the most recent valid composition. Please use
[subgraph check](/cli/subgraph/check) to understand the impact of your change.
## Description
The `wgc grpc-service delete` command allows you to delete a gRPC subgraph on the Cosmo platform's control plane. When you delete a gRPC subgraph, all associated data and configurations will be permanently removed. Use this command with caution, as the action cannot be undone.
## Parameters
* ``: The name of the gRPC subgraph you want to delete. This should be the exact name of the gRPC subgraph you wish to remove.
## Options
* `-n, --namespace [string]`: The namespace of the gRPC subgraph (Default: "default").
* `-f, --force`: An optional flag that allows you to force delete the gRPC subgraph without being prompted for confirmation. Use this option if you want to delete the gRPC subgraph without additional prompts.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
1. Delete the gRPC subgraph named "users-service":
```bash theme={"system"}
wgc grpc-service delete users-service
```
2. Force delete the gRPC subgraph named "users-service" without confirmation:
```bash theme={"system"}
wgc grpc-service delete users-service -f
```
3. Delete a gRPC subgraph in a specific namespace:
```bash theme={"system"}
wgc grpc-service delete users-service -n production
```
## Notes
* The `wgc grpc-service delete` command interacts with the Cosmo platform's control plane to delete the specified gRPC subgraph.
* When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental data loss.
* If composition errors occur during deletion, the gRPC subgraph will still be deleted, but the router will continue to work with the latest valid schema until the composition issues are resolved.
# Generate
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/generate
Generate a protobuf definition for a gRPC service from a GraphQL schema
# wgc grpc-service generate
The `generate` command generates a protobuf definition and mapping file for a gRPC service from a GraphQL schema,
which can be used to implement a gRPC service and can be used for the composition.
## Usage
```bash theme={"system"}
wgc grpc-service generate [options] [service-name]
```
## Arguments
| Argument | Description | Default |
| - | - | - |
| `service-name` | Name of the gRPC service | `service.v1` |
## Options
| Option | Description | Default |
| - | - | - |
| `-i, --input ` | The GraphQL schema file to generate a protobuf schema from | Required |
| `-o, --output ` | The output directory for the protobuf schema | `.` |
| `-p, --package-name ` | The name of the proto package | `service.v1` |
| `-g, --go-package ` | Adds an `option go_package` to the proto file | None |
## Description
This command generates a protobuf definition for a gRPC service from a GraphQL schema.
## Examples
### Generate a protobuf definition for a gRPC service from a GraphQL schema
```bash theme={"system"}
wgc grpc-service generate -i ./schema.graphql -o ./service MyService
```
### Define a custom package name
```bash theme={"system"}
wgc grpc-service generate -i ./schema.graphql -o ./service MyService --package-name my.custom.package
```
### Define a custom go package name
```bash theme={"system"}
wgc grpc-service generate -i ./schema.graphql -o ./service MyService --go-package github.com/wundergraph/cosmo/service/my-service
```
## Output
The command generates multiple files in the output directory:
* `service.proto`: The protobuf definition for the gRPC service
* `service.mapping.json`: The mapping file for the gRPC service
* `service.proto.lock.json`: The lock file for the protobuf definition
The generated protobuf definition can be used to implement a gRPC service in any language that supports protobuf.
The mapping and the protobuf definition is needed for the composition part.
See also: [gRPC Services](/router/gRPC/grpc-services) · [GraphQL Support for gRPC Integration](/router/gRPC/graphql-support)
# Init
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/init
Scaffold a new gRPC service project from a template
The `init` command scaffolds a new gRPC service project from a template,
downloading and extracting the template from the [wundergraph/cosmo-templates](https://github.com/wundergraph/cosmo-templates) repository.
## Usage
```bash theme={"system"}
wgc grpc-service init [options]
```
## Options
| Option | Description | Default |
| - | - | - |
| `-t, --template ` | Template to use | `typescript-connect-rpc-fastify` |
| `-d, --directory ` | Output directory for the new project | `.` |
## Description
* Downloads and extracts the specified template from the `wundergraph/cosmo-templates` GitHub repository under `grpc-service/`.
* Validates the template name and checks if it exists.
* Ensures the output directory is empty or creates it if it does not exist.
* Copies the template files into the output directory.
* Prints instructions to check the `README.md` in the generated project.
If the specified template does not exist, the command will list available templates and provide usage guidance.
## List available templates
To list available templates, you can use the [list-templates](/cli/grpc-service/list-templates) command.
## Examples
### Scaffold a new gRPC service with the default template
```bash theme={"system"}
wgc grpc-service init
```
### Scaffold a new gRPC service with a specific template
```bash theme={"system"}
wgc grpc-service init --template typescript-connect-rpc-fastify --directory ./my-grpc-service
```
## Output
The command creates a new directory (if it does not exist) and copies the template files into it. Check the generated `README.md` for instructions on how to use your new gRPC service project.
See also: [gRPC Services](/router/gRPC/grpc-services) · [GraphQL Support for gRPC Integration](/router/gRPC/graphql-support)
# List Templates
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/list-templates
List all available gRPC service templates for the init command.
The `list-templates` command lists all available gRPC service templates that can be used with the `wgc grpc-service init` command.
Templates are fetched from the [wundergraph/cosmo-templates](https://github.com/wundergraph/cosmo-templates) repository under the `grpc-service` directory.
## Usage
```bash theme={"system"}
wgc grpc-service list-templates
```
Once you've decided on a template, you can use the [init](/cli/grpc-service/init) command to scaffold a new gRPC service project from a template.
See also: [gRPC Services](/router/gRPC/grpc-services) · [GraphQL Support for gRPC Integration](/router/gRPC/graphql-support)
# Publish
Source: https://cosmo-docs.wundergraph.com/cli/grpc-service/publish
Publishes a gRPC subgraph on the control plane. If the gRPC subgraph doesn't exist, it will be created.
## Usage
```bash theme={"system"}
wgc grpc-service publish --schema --generated [options]
```
**Prerequisites**: Before publishing, you must first generate your protobuf
definitions using `wgc grpc-service generate` to create the required schema,
mapping, and lock files.
**Publish** is an irreversible action. However, the change will only be
visible to the routers once the composition has been successful. Until then,
the routers will operate with the most recent valid composition. Please use
[subgraph check](/cli/subgraph/check) to understand the impact of your change.
## Description
The `wgc grpc-service publish` command enables you to publish a gRPC subgraph to the Cosmo platform. Publishing a gRPC subgraph makes it available for use by federated graphs, allowing them to extend functionality through gRPC service integration. If the gRPC subgraph doesn't exist, it will be created automatically.
If the publication leads to composition errors, the errors will be visible in the Studio. The router will continue to work with the latest valid schema. Consider using the `wgc subgraph check` command to check for composition errors before publishing.
## Parameters
* ``: The name of the gRPC subgraph to publish.
## Options
### Required Options
* `--schema `: The schema file to upload to the subgraph.
* `--generated `: The path to the generated folder which contains the proto schema, mapping and lock files.
### Optional Options
If the gRPC subgraph has already been created previously, the `routing-url`
and `label` parameters will be ignored. Use [subgraph
update](/cli/subgraph/update) to update these values.
* `-n, --namespace [string]`: The namespace of the gRPC subgraph (Default: "default").
* `-r, --routing-url `: The routing URL of the gRPC subgraph. This is the URL at which the gRPC subgraph will be accessible. This parameter is always ignored if the subgraph has already been created.
* `--label [labels...]`: The labels to apply to the gRPC subgraph. The labels are passed in the format `= =`. This parameter is always ignored if the gRPC subgraph has already been created.
* Example: `--label team=backend environment=production`
If you are *creating* a gRPC subgraph for the first time with `grpc-service publish`, the `routing-url` and `label` parameters can be used to set these values. Note that a subgraph will only be considered for a federated graph composition if the subgraph's labels match the labels matcher of that federated graph.
If you are not creating a gRPC subgraph for the first time, the `routing-url` and `label` parameters will be ignored. To update these values for an existing gRPC subgraph, use [subgraph update](/cli/subgraph/update).
* `--fail-on-composition-error`: If set, the command will fail if the composition of the federated graph fails.
* `--fail-on-admission-webhook-error`: If set, the command will fail if the admission webhook fails.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Required Files
The generated folder must contain the following files (created automatically by `wgc grpc-service generate`):
* `service.proto`: The protobuf schema file
* `mapping.json`: The GraphQL-to-protobuf mapping file
* `service.proto.lock.json`: The protobuf lock file
## Examples
### Publish a gRPC subgraph
```bash theme={"system"}
wgc grpc-service publish users-service \
--schema ./src/schema.graphql \
--generated ./generated
```
### Create and publish a gRPC subgraph with routing URL and labels
```bash theme={"system"}
wgc grpc-service publish users-service \
--schema ./src/schema.graphql \
--generated ./generated \
--routing-url http://localhost:4001/graphql \
--label team=backend environment=production
```
### Publish with custom namespace
```bash theme={"system"}
wgc grpc-service publish users-service \
--schema ./src/schema.graphql \
--generated ./generated \
--namespace production
```
### Publish with error handling flags
```bash theme={"system"}
wgc grpc-service publish users-service \
--schema ./src/schema.graphql \
--generated ./generated \
--fail-on-composition-error \
--fail-on-admission-webhook-error
```
## Typical Workflow
Here's the recommended workflow for developing and publishing a gRPC subgraph:
1. **Create your GraphQL schema**:
Create a `schema.graphql` file with your GraphQL schema definition.
2. **Generate the protobuf definitions**:
```bash theme={"system"}
wgc grpc-service generate -i ./schema.graphql -o ./generated
```
This creates the required protobuf files: `service.proto`, `mapping.json`, and `service.proto.lock.json`.
3. **Develop your gRPC service**: Implement your service based on the generated protobuf definitions
4. **Test your service locally**: Ensure your gRPC service works correctly
5. **Publish the subgraph**:
```bash theme={"system"}
wgc grpc-service publish users-service \
--schema ./schema.graphql \
--generated ./generated
```
## Process Overview
The publish command performs the following steps:
1. **File Validation**: Validates that the schema file and all required generated files exist and contain valid content
2. **Subgraph Creation**: Creates the subgraph if it doesn't exist (using routing URL and labels if provided)
3. **Schema Publication**: Publishes the GraphQL schema and protobuf definitions to the control plane
4. **Composition**: Triggers composition with other subgraphs in the federated graph
## Notes
* The `wgc grpc-service publish` command interacts with the Cosmo platform's control plane to publish the specified gRPC subgraph.
* All required files (schema file and generated folder contents) must exist and contain valid content before publishing.
* If composition errors occur during publication, the subgraph will still be published, but the router will continue to work with the latest valid schema until the composition issues are resolved.
* The routing URL and labels are only used when creating a new subgraph - they're ignored for existing subgraphs.
# Cosmo CLI
Source: https://cosmo-docs.wundergraph.com/cli/intro
The cosmo CLI tool: wgc. Used to manage the cosmo platform e.g. pushing schema, checking schemas, creating new projects, managing users, etc. It interacts with the control plane.
## Installation
Please ensure you have installed at least one version of Node.js that is in "long-term support" ([LTS](https://nodejs.org/en/about/previous-releases)).
The CLI tool is part of the npm registry. You can start using it by simply running the following command.
```bash theme={"system"}
npm install -g wgc@latest
```
or
```bash theme={"system"}
npx -y wgc@latest
```
**When using `bunx`**
Running `bunx wgc@latest` doesn't guarantee that you are going to run the latest version of the package (you can check the status of the [issue here](https://github.com/oven-sh/bun/issues/4989)). For this reason, we recommend using `npx` or `pnpm dlx`.
Cosmo CLI Tool, or `wgc`, is an essential companion for developers leveraging the powerful capabilities of the Cosmo platform. It simplifies the management of GraphQL schemas, projects, and users, making the process of building and maintaining GraphQL APIs a seamless and efficient experience. Empowered by `wgc`, developers can focus on delivering innovative GraphQL solutions while taking full advantage of Cosmo's advanced features and functionalities.
### Authentication
The CLI uses the following environment variables to authenticate with the control plane:
* `COSMO_API_KEY` - API key for the control plane (For Cosmo Cloud you get this token after account provisioning)
* `COSMO_API_URL` - URL of the control plane (Points to Cosmo Cloud by default but can be changed for self-hosted)
## Proxy Usage
Starting with version 0.63.0, the CLI can be used behind a company proxy. To enable this, set either the `HTTPS_PROXY` or `HTTP_PROXY` environment variable to your company’s proxy (e.g., `https://username:password@proxy.com`).
# Cosmo MCP Server
Source: https://cosmo-docs.wundergraph.com/cli/mcp
The Cosmo MCP Server allows developers to integrate Cosmo into their modern LLM/AI supported IDEs.
## Overview
The Cosmo MCP Server allows developers to integrate Cosmo into their modern LLM/AI supported IDEs.
The implementation is running fully on the client side using STDIO.
As such, the MCP Server requires no additional setup on your machine other than setting up the `wgc` CLI tool with an API key.
## Installation
To install the MCP Server, you'll need to create an API key and configure your IDE to use it.
### 1. Create a new API key
You can create an API key in [Cosmo Studio](https://cosmo.wundergraph.com).
![Graphs section with Members tab]()
### 2. Configure your IDE
Add the following configuration to your IDE's settings.
You'll need to replace `cosmo_` with your actual API key.
```json theme={"system"}
{
"mcpServers": {
"cosmo": {
"command": "npx wgc",
"args": ["mcp"],
"env": {
"COSMO_API_KEY": "cosmo_"
}
}
}
}
```
## Useful Prompts
Here are some example prompts you can use to get started.
### Setting the Context
```
For the whole conversation,
if not otherwise specified,
assume that we're always working in the context of the
Namespace "default"
and the Supergraph "mygraph".
```
### Schema Exploration
*Load the schema of the Supergraph and summarize the core features*
```
Supergraph: mygraph
Namespace: default
Show me the core features of this Supergraph.
```
***
*Find out which subgraphs are part of the Supergraph*
```
Supergraph: mygraph
Namespace: default
Which subgraphs are part of this Supergraph?
```
***
*Load the SDL of the Supergraph*
```
Supergraph: mygraph
Namespace: default
Show me the schema for this Supergraph.
```
***
*Explore sub-sections of the Supergraph schema*
```
Supergraph: mygraph
Namespace: default
Show me the schema for the Employee type in this Supergraph.
```
### Dream Query Workflow
```
Supergraph: mygraph
Namespace: default
Use the dream_query_workflow
to enable the following query
on this Supergraph:
query {
employees {
name
department {
name
}
}
}
```
The dream\_query\_workflow guides the AI model through the process of adding the necessary schema changes to your Subgraphs to enable a new use case in your Supergraph.
It will find out which Subgraphs are best to modify,
and it will verify that the changes are composable and backwards compatible.
### Schema Change Proposal Workflow
```
Supergraph: mygraph
Namespace: default
Use the schema_change_proposal_workflow
to add the field "age: Int!"
to the "Employee" type
in this Supergraph.
```
This workflow is a sub-workflow of the dream\_query\_workflow.
Instead of starting from a query,
it starts with instructions on what specifically to change in the schema.
### AI-assisted Router Configuration
*Use the Router Config Reference to make changes to the Router config*
```
Look into the cosmo_router_config_reference
and help me to configure a custom GraphQL endpoint
in my Router config: router.yaml
```
***
*Use the Router Config Reference to enable WebSockets*
```
Look into the cosmo_router_config_reference
and help me to enable WebSockets
in my Router config: router.yaml
```
### Documentation Search
*Use fulltext search on the documentation to enable specific features in the Router config*
```
Look into the cosmo documentation
and help me to properly configure CORS
in my Router config: router.yaml
```
***
*Use fulltext search on the documentation to understand the steps to publish a Subgraph*
```
Look into the cosmo documentation
and explain to me the steps to publish a Subgraph.
```
## All Available Tools (Reference)
The MCP server exposes several tools that an AI model can utilize:
### Subgraph Management
* **`list_subgraphs`**: Lists all subgraphs registered in your Cosmo Platform instance.
* *Use Case*: Discovering available subgraphs.
* **`get_subgraphs`**: Retrieves detailed information for specified subgraphs, including their GraphQL Schema Definition Language (SDL).
* *Use Case*: Inspecting the schema or configuration of specific subgraphs.
* **`introspect_subgraph`**: Introspects a running subgraph endpoint to retrieve its current GraphQL schema.
* *Use Case*: Fetching the latest schema directly from a subgraph instance, useful for verifying deployments or comparing against registered schemas.
* **`subgraph_verify_schema_changes`**: Validates proposed changes to a subgraph's schema. It checks for valid GraphQL SDL, composition compatibility with other subgraphs, and potential breaking changes against client traffic (optional).
* *Use Case*: Safely validating schema modifications before deployment.
### Supergraph (Federated Graph) Management
* **`list_supergraphs`**: Lists all federated graphs (Supergraphs) in your Cosmo Platform instance, optionally filtered by namespace.
* *Use Case*: Discovering available Supergraphs.
* **`fetch_supergraph`**: Fetches the composed schema (SDL and client schema) and configuration details for a specific Supergraph.
* *Use Case*: Examining the structure and configuration of a Supergraph.
* **`fetch_supergraph_router_config`**: Retrieves the router configuration (e.g., for WunderGraph Cosmo Router) for a specific Supergraph.
* *Use Case*: Obtaining the necessary configuration to run a compatible router instance.
* **`fetch_supergraph_subgraphs`**: Fetches a list of all subgraphs that are part of a specific Supergraph, including their individual schemas and routing information.
* *Use Case*: Understanding the composition of a Supergraph and its constituent subgraphs.
### Schema Evolution & Query Workflows
* **`schema_change_proposal_workflow`**: Generates a step-by-step guide or set of instructions for making a specific schema change to a Supergraph safely and effectively.
* *Use Case*: Assisting developers in planning and executing schema changes.
* **`dream_query_workflow`**: Takes a desired GraphQL query and generates instructions on the necessary schema modifications across relevant subgraphs to support that query within a Supergraph.
* *Use Case*: Streamlining the process of evolving the Supergraph schema to meet new data requirements expressed via GraphQL queries.
* **`verify_query_against_remote_schema`**: Validates a given GraphQL query against the schema of a deployed Supergraph in your Cosmo Platform instance.
* *Use Case*: Checking if a query is valid before integrating it into an application.
* **`verify_query_against_in_memory_schema`**: Validates a given GraphQL query against a provided Supergraph schema string (e.g., a locally composed schema).
* *Use Case*: Testing queries against local or proposed schema changes without needing a deployed Supergraph.
### Supergraph Changelog
* **`supergraph_changelog`**: Fetches the changelog for a federated graph / Supergraph.
* *Use Case*: Reviewing the history of schema changes and composition updates for a Supergraph.
### Router Configuration Verification
* **`verify_router_config`**: Verifies a provided Cosmo Router configuration (JSON or YAML) for validity.
* *Use Case*: Ensuring a proposed router configuration is syntactically correct and valid before deployment.
* **`cosmo_router_config_reference`**: Provides a reference for the Cosmo Router configuration.
* *Use Case*: Understanding the syntax and structure of the Cosmo Router configuration.
### Documentation Search
* **`search_docs`**: Searches the official WunderGraph Cosmo documentation for a given query.
* *Use Case*: Finding relevant documentation pages for specific features, concepts, or troubleshooting steps.
# Monograph
Source: https://cosmo-docs.wundergraph.com/cli/monograph
A monograph refers to a graph with GraphQL Federation disabled and is limited to a single subgraph.
Before you can interact with a monograph, you need to create it. Each monograph is mapped to a Cosmo Router service that can respond to the relevant GraphQL schema.
# Changelog
Source: https://cosmo-docs.wundergraph.com/cli/monograph/changelog
Retrieves the changelog for a monograph
## Usage
```bash theme={"system"}
npx wgc monograph changelog
```
## Description
The `npx wgc monograph changelog` command allows you to retrieve the changelog for a given monograph. By default it fetches the latest 10 schema versions from the past 3 days and writes to changelog.json file.
## Parameters
* ``: The name of the monograph you want to create. Replace `` with the name of your monograph.
## Options
`-n, --namespace` : The namespace of the monograph (Default: "default").
`-l, --limit`: The number of entries to fetch. Defaults to 10.
`-f, --offset`: Used for pagination. Sets the offset from which you want to query.
`-s, --start`: The start date in `MM-DD-YY` format. Defaults to 3 days ago from current date.
`-e, --end`: The end date in `MM-DD-YY` format. Defaults to today.
`-o, --out`: The destination file for the json output. Defaults to `changelog.json`
## Examples
```bash theme={"system"}
npx wgc monograph changelog production -s 08-15-23 -e 08-31-23 -o changes.json
```
Fetch first 10 changes from 8th August to 31st August for the graph `production` and write it to `changes.json` file.
```bash theme={"system"}
npx wgc monograph changelog production -s 08-15-23 -e 08-31-23 -l 10 -f 10 -o changes.json
```
Fetch the next 10 changes (after the ones in the previous example) from 8th August to 31st August for the graph `production` and write it to `changes.json` file.
## Sample output
```JSON theme={"system"}
[
{
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)",
"schemaVersionId": "4f46116d-b307-4bf4-8d24-1974e794819d",
"changelogs": [
{
"id": "2b1db820-6f93-42ac-80a2-b0f5a8d765f3",
"path": "ProductNames",
"changeType": "TYPE_ADDED",
"changeMessage": "Type 'ProductNames' was added",
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)"
},
{
"id": "0aaf1f49-2fb9-4528-85e4-f4b4b3c671ae",
"path": "Employee.products",
"changeType": "FIELD_ADDED",
"changeMessage": "Field 'products' was added to object type 'Employee'",
"createdAt": "Fri Sep 15 2023 21:25:26 GMT+0530 (India Standard Time)"
}
]
},
..more versions
]
```
# Check
Source: https://cosmo-docs.wundergraph.com/cli/monograph/check
Checks for breaking changes and composition errors in the proposed schema for the monograph.
## Usage
### Check schema changes
```bash theme={"system"}
npx wgc monograph check --schema
```
Use this command whenever you make modifications to your monograph schema. It will report any GraphQL or composition errors before they land on production. The report will be made visible under [Schema Checks](/studio/schema-checks).
## Description
The `npx wgc monograph check` command checks for breaking changes and composition errors in the proposed schema. This validation process ensures that the new schema you intend to use does not introduce any issues that could negatively impact the monograph.
## Parameters
* ``: The name of the monograph for which you want to perform the validation check.
## Options
* `-n, --namespace` : The namespace of the monograph (Default: "default").
* `--schema `: The path to the new schema file that you want to validate. This file should contain the complete schema definition in the GraphQL Schema Definition Language (SDL) format.
* `-j, --json`: Prints the check result in JSON format instead of table output. Useful for CI/CD automation and scripts.
* `-o, --out [string]`: Writes the JSON check result to a destination file. This option enables JSON output automatically.
## Example
Check for breaking changes and composition errors for the monograph "production" in the default namespace with the new schema file located at "./schemas/new\_schema.graphql":
```bash theme={"system"}
npx wgc monograph check production -n default --schema ./schemas/new_schema.graphql
```
Output the check result as JSON for automation:
```bash theme={"system"}
npx wgc monograph check production -n default --schema ./schemas/new_schema.graphql --json
```
Write the JSON check result to a file:
```bash theme={"system"}
npx wgc monograph check production -n default --schema ./schemas/new_schema.graphql --out ./check-result.json
```
## Sample output with changes and errors
Changes
| CHANGE | TYPE | DESCRIPTION |
| - | - | - |
| BREAKING | FIELD\_REMOVED | Field 'email' was removed from object type 'User' |
| NON-BREAKING | FIELD\_ADDED | Field 'emailID' was added to object type 'User' |
## Usage in CI and GitHub Integration
Checkout the tutorial [here](/tutorial/pr-based-workflow-for-federation) on how to use the check command in CI with GitHub.
## Notes
* The `npx wgc monograph check` command interacts with the Cosmo platform's control plane to perform the validation checks.
* If there are no breaking changes or composition errors detected, the tables will be empty, indicating that the new schema is safe to be used in production.
# Create
Source: https://cosmo-docs.wundergraph.com/cli/monograph/create
Creates a monograph on the control plane.
## Usage
```bash theme={"system"}
npx wgc monograph create -r -u
```
## Description
The `npx wgc monograph create` command allows you to create a new monograph on the Cosmo platform's control plane. A monograph does not allow for GraphQL Federation as it is strictly limited to one subgraph. This subgraph is automatically created for you internally and you do not need to interact with it directly.
## Parameters
* ``: The name of the monograph you want to create. Replace `` with the desired name for your monograph.
## Required Options
`-r , --routing-url`: The routing URL of your router. This URL defines the endpoint where the router will be accessible. The monograph will be accessible through this router.
`-u , --graph-url`: The url of your GraphQL server that is accessible from the router.
## Other Options
* `-n, --namespace` : The namespace of the monograph (Default: "default").
* `--admission-webhook-url ` the base url of the admission webhook. This is the url that the controlplane will use to implement admission control for the federated graph. Example: `https://admission.example.com` (without the `/validate-config` path name)
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url. The header containing this signature is `X-Cosmo-Signature-256`
* `--subscription-url:` Optionally, use a different URL for subscription requests. If no subscription URL is provided, the router URL is used for subscriptions.
* `--subscription-protocol:` Optionally, set a protocol to use for subscriptions. The available options are:
* `ws` (default): Negotiate an appropriate protocol over websockets. Both `graphql-ws` and `subscription-transport-ws` are supported.
* `sse`: Use Server-Sent Events with a GET request.
* `sse_post`: Use Server-Sent events with a POST request.
* `--readme` : The markdown file which describes the monograph.
* `--websocket-subprotocol:` The subprotocol to use when subscribing to the monograph. The supported protocols are auto(default), graphql-ws, and graphql-transport-ws. It should be used only if the subscription protocol is ws.
## Examples
```bash theme={"system"}
npx wgc monograph create production -r http://router.example.com/graphql -u https://spacex-production.up.railway.app
```
Create a monograph named "production" with a routing URL of "[http://router.example.com/graphql](http://router.example.com/graphql)" and a GraphQL server endpoint of [https://spacex-production.up.railway.app](https://spacex-production.up.railway.app).
## Notes
* The `npx wgc monograph create` command interacts with the Cosmo platform's control plane to create the specified monograph.
* The routing URL of the router should be accessible by the monograph to handle incoming queries and route them to the GraphQL server.
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/monograph/delete
Deletes a monograph on the control plane.
## Usage
```bash theme={"system"}
npx wgc monograph delete [-f, --force]
```
**Delete** is an irreversible action. It will delete the monograph and the single connected subgraph, including versions, schema checks, etc.
## Description
The `npx wgc monograph delete` command allows you to delete a monograph on the Cosmo platform's control plane. Deleting a monograph will remove its configuration and associated resources. Use this command with caution, as the action cannot be undone.
## Parameters
* ``: The name of the monograph you want to delete. Replace `` with the name of the monograph you wish to remove.
## Options
`-n, --namespace` : The namespace of the monograph (Default: "default").
`-f, --force` : An optional flag that allows you to force delete the monograph without being prompted for confirmation. Use this option if you want to delete the monograph without additional prompts.
## Examples
```bash theme={"system"}
npx wgc monograph delete production
```
Delete the monograph named "production".
```bash theme={"system"}
npx wgc monograph delete production -f
```
Force delete the monograph named "production" without confirmation.
## Notes
* The `npx wgc monograph delete` command interacts with the Cosmo platform's control plane to delete the specified monograph. Ensure that you have the necessary permissions to perform this operation.
* When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental deletions.
# Fetch Schema
Source: https://cosmo-docs.wundergraph.com/cli/monograph/fetch
Fetches the latest valid SDL of a monograph. The output can be piped to a file. This is primarily used for debugging purposes
## Usage
```bash theme={"system"}
npx wgc monograph fetch-schema
```
## Description
The `npx wgc monograph fetch-schema` command allows you to fetch the latest valid Schema Definition Language (SDL) of a monograph from the Cosmo platform's control plane. You can use this command to retrieve the SDL and, if needed, pipe the output to a file.
By default, the output schema is set to the **Router Schema**. To use the **Client Schema** instead, specify the `-c` or `--client-schema` flag to the command.
## Parameters
* ``: The name of the monograph you want to fetch. Replace `` with the name of the monograph you wish to retrieve the SDL for.
## Options
* `-n, --namespace` : The namespace of the monograph (Default: "default").
* `-o, --out` : Destination file for the SDL. Prints to standard output if not provided.
* `-c, --client-schema`: Output the Client Schema instead of the default Router Schema.
## Examples
```bash theme={"system"}
npx wgc monograph fetch-schema production
```
Fetch the latest valid SDL of the monograph named "production."
```bash theme={"system"}
npx wgc monograph fetch-schema production -o production-schema.graphql
```
Fetch the latest valid SDL of the monograph named "production" and save it to a file named "production-schema.graphql."
```bash theme={"system"}
npx wgc monograph fetch-schema production --client-schema
```
Fetch the latest valid client SDL of the monograph named "production".
## Notes
* The `npx wgc monograph fetch-schema` command interacts with the Cosmo platform's control plane to fetch the latest valid SDL of the specified monograph. Ensure that you have the necessary permissions to perform this operation.
# List
Source: https://cosmo-docs.wundergraph.com/cli/monograph/list
Lists all the monographs.
## Usage
```bash theme={"system"}
npx wgc monograph list
```
## Description
The `npx wgc monograph list` command allows you to list all the monographs under your organization.
## Options
* `-n, --namespace` : Filter to get graphs in this namespace only.
* `-r, --raw` : Prints to the console in json format instead of table (Deprecated).
* `-j, --json` : Prints to the console in json format instead of table.
* `-o, --out` : Destination file for the json output. Has precedence over both `raw` and `json`
# Migrate
Source: https://cosmo-docs.wundergraph.com/cli/monograph/migrate
Converts the monograph into a federated graph. Once done you can update label matchers and labels to compose with more graphs in your organization.
## Usage
```bash theme={"system"}
npx wgc monograph migrate
```
## Description
The `npx wgc monograph update` command allows you to migrate an existing monograph to a federated graph.
IMPORTANT: Migration will assign new labels to the graph and underlying subgraph. Since the new labels are unique, recomposition does not take palce. After migration, you can update the labels to your desired ones to compose with other graphs in the namespace.
## Parameters
* ``: The name of the monograph you want to migrate.
## Options
* `-n, --namespace` : The namespace of the monograph (Defaults to 'default')
# Move
Source: https://cosmo-docs.wundergraph.com/cli/monograph/move
Moves the monograph from one namespace to another.
## Usage
```bash theme={"system"}
npx wgc monograph move -n fromNS -t toNS
```
Moving a monograph will also move the single underlying subgraph. No recomposition takes place.
## Description
The `npx wgc monograph move` command allows you to move a monograph into a different namespace.
## Parameters
* ``: The name of the monograph you want to move.
## Options
* `-n, --namespace` : The namespace of the monograph.
* `-t, --to`: The new namespace of the monograph.
## Example
Moves the monograph named "mygraph" into the "production" namespace.
```bash theme={"system"}
npx wgc monograph move mygraph -n default -t production
```
# Publish
Source: https://cosmo-docs.wundergraph.com/cli/monograph/publish
Publishes a monograph on the control plane.
## **Usage**
```bash theme={"system"}
npx wgc monograph publish [monographName] --schema [schemaFilePath]
```
## **Description**
The `npx wgc monograph publish` command enables you to publish a specific monograph to the Cosmo platform. Publishing a monograph makes it available for consumption by other services or applications, allowing them to send GraphQL queries and retrieve data from your monograph.
## **Parameters**
* `[monographName]`: The name of the monograph you want to publish. Make sure to use the correct name of the monograph you previously created.
## **Options**
* `-n, --namespace` : The namespace of the monograph (Default: "default").
* `--schema`: The file path to the GraphQL schema definition for the monograph you want to publish. This file should contain the complete schema definition in the GraphQL Schema Definition Language (SDL) format.
* Example: `--schema ../production.graphql`
* `--fail-on-admission-webhook-error `: If set, the command will fail if the admission webhook fails
* `--fail-on-composition-error `: If set, the command will fail if the composition of the monograph fails.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## **Example**
### Publish a schema to an existing monograph.
```bash theme={"system"}
npx wgc monograph publish production --schema ../production.graphql
```
## **Notes**
* The `npx wgc monograph publish` command interacts with the Cosmo platform's control plane to publish the specified monograph.
* Double-check that the path provided for the `--schema` option points to the correct location of the GraphQL schema file you intend to publish.
# Update
Source: https://cosmo-docs.wundergraph.com/cli/monograph/update
Updates monograph metadata like URL, subscription configuration and more on the control plane.
## Usage
```bash theme={"system"}
npx wgc monograph update [-r, --routing-url ] [--readme ]
```
## Description
The `npx wgc monograph update` command allows you to update an existing monograph on the Cosmo platform's control plane. With this command, you can modify the routing URL, graphql server endpoint, subscription configuration and readme.
## Parameters
* ``: The name of the monograph you want to update. This should be the exact name of the monograph you wish to modify.
## Options
* `-n, --namespace` : The namespace of the monograph (Default: "default").
* `-r, --routing-url `: This is the url that the router will be accessible at.
* `-u, --graph-url `: The url of your GraphQL server that is accessible from the router.
* `--subscription-url:` Optionally, use a different URL for subscription requests. If no subscription URL is provided, the router URL is used for subscriptions. To remove a previously set subscription URL, use the flag without provided a URL argument.
* `--subscription-protocol:` Optionally, set a protocol to use for subscriptions. The available options are:
* `ws` (default): Negotiate an appropriate protocol over websockets. Both `graphql-ws` and `subscription-transport-ws` are supported.
* `sse`: Use Server-Sent Events with a GET request.
* `sse_post`: Use Server-Sent events with a POST request.
* `--readme :` The path to the markdown file which describes the monograph.
* `--websocket-subprotocol:` The subprotocol to use when subscribing to the monograph. The supported protocols are auto(default), graphql-ws, and graphql-transport-ws. It should be used only if the subscription protocol is ws.
* `--admission-webhook-url ` the base url of the admission webhook. This is the url that the controlplane will use to implement admission control for the federated graph.
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url. The header containing this signature is `X-Cosmo-Signature-256`
## Example
Update the routing URL of the monograph "production":
```bash theme={"system"}
npx wgc monograph update production -r http://new-domain.com/graphql
```
## Notes
* The `npx wgc monograph update` command interacts with the Cosmo platform's control plane to update the specified monograph.
* You can combine the options in a single command to update multiple things.
# Version
Source: https://cosmo-docs.wundergraph.com/cli/monograph/version
# Get
Source: https://cosmo-docs.wundergraph.com/cli/monograph/version/get
Retrieves and displays the router compatibility version that has been set for a specific monograph.
## Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.74.0](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.74.0) |
## Usage
```bash theme={"system"}
npx wgc monograph version get
```
## Description
The `wgc monograph version get` command retrieves and displays the router compatibility version that has been set for a specific monograph.
## Output
The router compatibility version that has been set for the monograph.
## Example
```bash theme={"system"}
> npx wgc monograph version get mygraph -n prod
┌────────────┬───────────┬─────────┐
│ GRAPH NAME │ NAMESPACE │ VERSION │
├────────────┼───────────┼─────────┤
│ mygraph │ prod │ 1 │
└────────────┴───────────┴─────────┘
```
# Set
Source: https://cosmo-docs.wundergraph.com/cli/monograph/version/set
Set the router compatibility version for a specific monograph.
Currently, there is only one router compatibility version. Consequently, this command does not yet serve a meaningful function (but will in the near future).
## Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.74.0](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.74.0) |
## Usage
```bash theme={"system"}
npx wgc monograph version set --version
```
## Arguments
| Description | Type |
| - | - |
| The name of the monograph. | string |
## Options
| Option | Type | Value | Required | Default value |
| - | - | - | - | - |
| `--version/-v` | string | The router compatibility version to be set. | true | |
| `--namespace/-n` | string | The namespace where the monograph exists. | false | "default" |
## Description
The `wgc monograph version set` command allows a [valid router compatibility version](/cli/router/compatibility-version/list) to be set for a monograph.
## Output
If successful, a table will display the graph name, its namespace, the previous router compatibility version, and the current router compatibility version.
## Example
```bash theme={"system"}
> npx wgc federated-graph version set mygraph -v 1
✔ Successfully set the router compatibility version for federated graph "prod" to 1.
┌────────────┬───────────┬──────────────────┬─────────────┐
│ GRAPH NAME │ NAMESPACE │ PREVIOUS VERSION │ NEW VERSION │
├────────────┼───────────┼──────────────────┼─────────────┤
│ prod │ default │ 2 │ 1 │
└────────────┴───────────┴──────────────────┴─────────────┘
```
# Namespace
Source: https://cosmo-docs.wundergraph.com/cli/namespace
Commands to manage namespaces within the organization
Namespaces are a way to isolate your federated graphs and subgraphs. They are the way to group graphs in different environments, such as production and staging. For example you can have a federated graph called `my-api` in a production and staging namespace. All graph operations and compositions are scoped to graphs present in a particular namespace. Every organization is provided a `default` namespace which cannot be deleted. You can scope CLI commands to a particular namespace by passing the `-n` flag or `default` is considered.
# Create
Source: https://cosmo-docs.wundergraph.com/cli/namespace/create
Creates a namespace for the organization on the control plane
## Description
The `npx wgc namespace create` command allows you to create a new namespace within the organization.
Namespaces must be created before they can be used. For example, you need to create a namespace before adding a graph to it.
## Usage
```bash theme={"system"}
npx wgc namespace create [name]
```
## **Parameters**
* `[name]`: The name of the namespace you want to create.
## **Example**
* Create a new namespace named "production"
```bash theme={"system"}
npx wgc namespace create production
```
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/namespace/delete
Allows you to delete a namespace
## Usage
```bash theme={"system"}
npx wgc namespace delete [name]
```
## Description
The `npx wgc namespace delete` command allows you to delete a namespace within the organization.
Deleting a namespace will delete all resources (federated graphs and subgraphs) within it. Please use the command carefully. Only admins and creators of the namespace can perform this action.
## **Parameters**
* `[name]`: The name of the namespace you want to delete.
## Options
* `-f, --force`: An optional flag that allows you to force delete the namespace without being prompted for confirmation.
## **Example**
* Delete a namespace named "production"
```bash theme={"system"}
npx wgc namespace delete production
```
# List
Source: https://cosmo-docs.wundergraph.com/cli/namespace/list
List all namespaces within the organization
## Usage
```bash theme={"system"}
npx wgc namespace list
```
## Description
The `npx wgc namespace list` command allows you to view all namespaces within the organization.
## Options
* `-r, --raw` : Prints to the console in json format instead of table (Deprecated).
* `-j, --json` : Prints to the console in json format instead of table.
* `-o, --out` : Destination file for the json output. Has precedence over both `raw` and `json`
# Rename
Source: https://cosmo-docs.wundergraph.com/cli/namespace/rename
Rename an existing namespace within the organization
## Usage
```bash theme={"system"}
npx wgc namespace rename [name] --to [new name]
```
## Description
The `npx wgc namespace rename` command allows you to rename an existing namespace within the organization.
## **Parameters**
* `[name]`: The name of the namespace you want to rename.
## Options
* `-t, --to`: A required flag with the new name for the namespace
## **Example**
Rename a namespace from "prod" to "production"
```bash theme={"system"}
npx wgc namespace rename prod --to production
```
# Operations
Source: https://cosmo-docs.wundergraph.com/cli/operations
Manipulate registered operations
# Push
Source: https://cosmo-docs.wundergraph.com/cli/operations/push
Push persisted operations to your routers
### Usage
```bash theme={"system"}
wgc operations push -c -f
```
### Description
Pushes the provided operations to the control plane, enabling them to be used from the router when using the given `graph_name`. Additionally, it registers the given `client_name` as a well-known client.
The operations file might be one of the following formats:
* Plain `.graphql` or `.gql` file
* An [Apollo operation manifest](https://www.apollographql.com/docs/kotlin/advanced/persisted-queries/#1-generate-operation-manifest)
* A [Relay Query Map](https://relay.dev/docs/guides/persisted-queries/)
The operations are validated against the graph schema before registering them. If any of the operations is invalid, no operations will be registered.
### Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-c, --client-name ` The client name / identifier to register these operations under. By default, the client name must be sent by the client at request time via the `graphql-client-name` HTTP header. When the router runs in [manifest mode](/router/persisted-queries/persisted-operations#pql-manifest), the client name is used only for organizational structure in the Studio (e.g. you could use `"default"`) and is not matched against incoming requests.
* `-f, --file ` Filename to read operations from. This argument can be used multiple times to read operations from multiple files. See [Description](/cli/operations/push#description) for a list of the supported file formats.
* `-q, --quiet` Don't produce any output, just exit with success or error. Intended for use in CI checks.
* `--format ` Specify an output format for the returned data. Support types include `text` (the default) and `json.`
# Proposal
Source: https://cosmo-docs.wundergraph.com/cli/proposal
Manage proposals of federated graph
The `proposal` command and its subcommands provide functionality to manage proposals of federated graph.
Create a new proposal for a federated graph
Update an existing proposal for a federated graph
Approve or close an existing proposal from a local or CI environment
# Create
Source: https://cosmo-docs.wundergraph.com/cli/proposal/create
Creates a proposal for a federated graph.
## Usage
```bash theme={"system"}
npx wgc proposal create --federation-graph (--subgraph --new-subgraph --deleted-subgraph )... [options]
```
A proposal allows you to propose changes to a federated graph and review them
before applying.
## Description
The `npx wgc proposal create` command allows you to create a new proposal for federated graph changes within the Cosmo platform. Proposals provide a way to suggest and review modifications to subgraphs within a federated graph before applying them. You can include existing subgraphs with schema changes, add new subgraphs, or remove existing subgraphs in a proposal.
## **Parameters**
* `[name]`: The name of the proposal you want to create. It should be a descriptive identifier for the proposal.
## **Options**
* `-f, --federation-graph ` (required): The name of the federated graph this proposal is for.
* `-n, --namespace [namespace]` : The namespace of the federated graph (Default: "default").
* `--subgraph `: Specify a subgraph to include in the proposal with its updated schema. Can be specified multiple times for different subgraphs.
* Format: `name:subgraph-name,schemaPath:path-to-schema`
* Example: `--subgraph name:products,schemaPath:./schemas/products.graphql`
* `--new-subgraph `: Specify a new subgraph to add in the proposal. Can be specified multiple times.
* Format: `name:subgraph-name,schemaPath:path-to-schema,labels:"key=value key=value"`
* Example: `--new-subgraph name:reviews,schemaPath:./schemas/reviews.graphql,labels:"team=B department=engineering"`
* The labels must match the label matchers of the federated graph the proposal is for. Otherwise the command fails, since the new subgraph would not be part of that federated graph.
* `--deleted-subgraph `: Specify a subgraph to be deleted in the proposal. Can be specified multiple times.
* Example: `--deleted-subgraph legacy-products`
At least one of `--subgraph`, `--new-subgraph`, or `--deleted-subgraph` must be provided.
## **Examples**
### Update an existing subgraph
```bash theme={"system"}
npx wgc proposal create update-products --federation-graph my-graph --subgraph name:products,schemaPath:./schemas/products.graphql
```
### Add a new subgraph
```bash theme={"system"}
npx wgc proposal create add-reviews --federation-graph my-graph --new-subgraph name:reviews,schemaPath:./schemas/reviews.graphql,labels:"team=product"
```
### Remove a subgraph
```bash theme={"system"}
npx wgc proposal create remove-legacy --federation-graph my-graph --deleted-subgraph legacy-products
```
### Complex proposal with multiple changes
```bash theme={"system"}
npx wgc proposal create quarterly-update --federation-graph my-graph \
--subgraph name:products,schemaPath:./schemas/products.graphql \
--new-subgraph name:reviews,schemaPath:./schemas/reviews.graphql,labels:"team=product" \
--deleted-subgraph legacy-products
```
# Update
Source: https://cosmo-docs.wundergraph.com/cli/proposal/update
Updates an existing proposal for a federated graph.
## Usage
```bash theme={"system"}
npx wgc proposal update --federation-graph (--subgraph --new-subgraph --deleted-subgraph )... [options]
```
This command allows you to modify an existing proposal before it is approved.
Note that any subgraphs you pass will override the corresponding subgraphs in
the current proposal - the command does not merge changes incrementally.
## Description
The `npx wgc proposal update` command enables you to update an existing proposal for federated graph changes within the Cosmo platform. You can modify the proposal by adding, updating, or removing subgraphs from the proposal. This is useful when you need to make adjustments to a proposal that has not yet been approved.
When you specify subgraphs in the update command, they will completely replace the corresponding subgraphs in the existing proposal. The update is not incremental - each subgraph you provide through the command options will override any previous version of that subgraph in the proposal. If you need to maintain some existing changes while adding new ones, make sure to include all the subgraphs you want in the final proposal.
## **Parameters**
* `[name]`: The name of the existing proposal you want to update.
## **Options**
* `-f, --federation-graph ` (required): The name of the federated graph this proposal is for.
* `-n, --namespace [namespace]` : The namespace of the federated graph (Default: "default").
* `--subgraph `: Specify a subgraph to update in the proposal with its updated schema. Can be specified multiple times for different subgraphs.
* Format: `name:subgraph-name,schemaPath:path-to-schema`
* Example: `--subgraph name:products,schemaPath:./schemas/products-updated.graphql`
* `--new-subgraph `: Specify a new subgraph to add to the proposal. Can be specified multiple times.
* Format: `name:subgraph-name,schemaPath:path-to-schema,labels:"key=value key=value"`
* Example: `--new-subgraph name:inventory,schemaPath:./schemas/inventory.graphql,labels:"team=B department=operations"`
* The labels must match the label matchers of the federated graph the proposal is for. Otherwise the command fails, since the new subgraph would not be part of that federated graph.
* `--deleted-subgraph `: Specify a subgraph to be deleted in the proposal. Can be specified multiple times.
* Example: `--deleted-subgraph outdated-service`
At least one of `--subgraph`, `--new-subgraph`, or `--deleted-subgraph` must be provided.
## **Examples**
### Update a subgraph in an existing proposal
```bash theme={"system"}
npx wgc proposal update product-changes --federation-graph my-graph --subgraph name:products,schemaPath:./schemas/products-revised.graphql
```
### Add another new subgraph to an existing proposal
```bash theme={"system"}
npx wgc proposal update service-expansion --federation-graph my-graph --new-subgraph name:inventory,schemaPath:./schemas/inventory.graphql,labels:"team=operations"
```
### Mark an additional subgraph for deletion in an existing proposal
```bash theme={"system"}
npx wgc proposal update legacy-cleanup --federation-graph my-graph --deleted-subgraph another-legacy-service
```
### Multiple updates to an existing proposal
```bash theme={"system"}
npx wgc proposal update revised-plan --federation-graph my-graph \
--subgraph name:products,schemaPath:./schemas/products-final.graphql \
--new-subgraph name:analytics,schemaPath:./schemas/analytics.graphql,labels:"team=data" \
--deleted-subgraph unused-service
```
Remember that each subgraph specified in the update command will override the
corresponding subgraph in the existing proposal. If you want to keep existing
changes for other subgraphs, you must include them in your update command as
well.
# Update Status
Source: https://cosmo-docs.wundergraph.com/cli/proposal/update-status
Updates the status of an existing proposal for a federated graph.
## Usage
```bash theme={"system"}
npx wgc proposal update-status --federation-graph --status [options]
```
## Description
The `npx wgc proposal update-status` command updates an existing proposal's review status. The command is non-interactive, which makes it suitable for CI workflows.
The API key used by the command must have write access to the federated graph.
## **Parameters**
* `[name]`: The name of the proposal to update.
## **Options**
* `-f, --federation-graph ` (required): The name of the federated graph this proposal is for.
* `-s, --status ` (required): The status to set. Accepted values are `approved` and `closed`. Values are case-insensitive.
* `-n, --namespace [namespace]`: The namespace of the federated graph (Default: `default`).
* `-j, --json`: Prints structured JSON instead of text.
## **CI examples**
Configure an API key as a secret in your CI system and expose it as `COSMO_API_KEY` before running the command.
Approve a proposal:
```bash theme={"system"}
export COSMO_API_KEY=
npx wgc proposal update-status product-changes \
--federation-graph my-graph \
--namespace production \
--status approved \
--json
```
Close a proposal:
```bash theme={"system"}
npx wgc proposal update-status product-changes \
--federation-graph my-graph \
--namespace production \
--status closed
```
The command exits with a non-zero status when the proposal status cannot be updated, allowing the CI job to fail immediately.
# Router
Source: https://cosmo-docs.wundergraph.com/cli/router
# Cache
Source: https://cosmo-docs.wundergraph.com/cli/router/cache
# Push
Source: https://cosmo-docs.wundergraph.com/cli/router/cache/push
### Usage
```
wgc router cache push -n -f
```
### Description
Pushes new cache warmer operations to the registry. These manually added operations will have precedence over the operations computed based on latency.
### Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-o, --operation-name ` : The name of the operation.
* `-f, --file ` : The file containing the operation to push. Supports `.graphql` and `.gql`
* `-p, --persisted-operation-id ` : The ID of the persisted operation to be pushed.
If both a file and a persisted operation ID are provided, the persisted operation ID takes precedence.
### **Examples**
Push an operation using a file:
```bash theme={"system"}
wgc router cache push my-graph -f operation.graphql
```
Push an operation using a persisted operation ID:
```bash theme={"system"}
wgc router cache push my-graph -p fb16e56456d13f6e52a4a2316b79
```
# Compatibility Version
Source: https://cosmo-docs.wundergraph.com/cli/router/compatibility-version
The `compatibility-version` commands relate to a router's compatibility version.
Please see [Router Compatibility Versions](/concepts/router-compatibility-versions) for an overview on the topic.
# List
Source: https://cosmo-docs.wundergraph.com/cli/router/compatibility-version/list
Lists all supported router compatibility versions.
## Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.74.0](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.74.0) |
## Usage
```bash theme={"system"}
npx wgc router compatibility-version list
```
## Description
The `wgc router compatibility-version list` command lists all router compatibility versions supported by WunderGraph Cosmo Cloud.
## Output
A table of router compatibility versions currently supported by WunderGraph Cosmo Cloud.
## Example
```bash theme={"system"}
> npx wgc router compatibility-version list
The router compatibility versions currently supported are:
┌─────────┬───┐
│ VERSION │ 1 │
└─────────┴───┘
```
# Compose
Source: https://cosmo-docs.wundergraph.com/cli/router/compose
Compose generates the router execution config locally from your subgraphs. The config can be used to start your router with a pre-built router config.
IMPORTANT: Please note that since this command runs locally, the subgraphs may or may not exist on the control plane. It is recommended to **not** use this for production, if you plan to use the Cosmo platform as schema registry or analytics platform. For production, you can fetch the latest router execution config for your federated graph using the [fetch](/cli/router/fetch) command instead.
## Usage
```bash theme={"system"}
npx wgc router compose -i
```
## Description
The `npx wgc router compose` command allows you to compose subgraphs and build a router execution config locally without a connection to the control plane.
## Options
* `-i, --input`: The path to the input config file that contains information about your subgraphs.
* `-o, --out` : Destination file for the router config. Prints to standard output if not provided.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
* `--split-configs-enabled`: This flag enables splitting the router config into multiple files.
* `--exclude [tags...]`: Schema elements with these tags will be excluded from the composed schema.
Providing exclude and/or include tags produces a contract of the supergraph rather than the full supergraph.
* `--include [tags...]`: Schema elements with these tags will be included in the composed schema.
Providing exclude and/or include tags produces a contract of the supergraph rather than the full supergraph.
* `--disable-base-contract`: Specifies whether a contract for the base federated graph should be created.
Yields an error if supplied without any included or excluded tags.
* `--contract-feature-flag-names [feature-flag-names...]`: Specifies that a contract for one or more specific feature flags should be created.
Yields an error if supplied without any included or excluded tags.
Note: The `--split-configs-enabled` flag requires Router version [0.315.0](https://github.com/wundergraph/cosmo/releases/tag/router%400.315.0) or higher.
## Input file structure
```bash theme={"system"}
version: 1
subgraphs:
# You can either provide schema file or introspection. File takes precedence
- name: employees
routing_url: http://localhost:4001/graphql
schema:
file: ./employees.graphql
subscription:
url: http://localhost:4001/sse #Optional, defaults to routing_url
protocol: sse # Optional, defaults to ws (websockets)
websocket_subprotocol: graphql-ws # Optional, defaults to auto.
# Available options are auto, graphql-ws, graphql-transport-ws
- name: family
routing_url: http://localhost:4002/graphql
introspection:
url: http://localhost:4002/graphql
headers:
Authorization: 'Bearer YOUR_TOKEN_HERE'
```
## Feature flags (optional)
You can define feature flags in the input file so the composed router config includes alternate subgraphs when a flag is active. Each flag lists one or more `feature_graphs` that describe the replacement subgraph to serve when the flag is enabled (e.g. via the `X-Feature-Flag` header). For an overview of how the router uses feature flags, see [Feature Flags](/router/feature-flags).
```yaml theme={"system"}
feature_flags:
- name: test_checkout
feature_graphs:
- name: checkout_canary
subgraph_name: checkout
routing_url: https://api.example.com/checkout-canary/graphql
schema:
file: feature-flag_checkout.graphql
subgraphs:
- name: checkout
routing_url: https://api.example.com/checkout/graphql
schema:
file: checkout.graphql
```
## Contracts (optional)
By default, `compose` produces the full supergraph.
Passing `--exclude` and/or `--include` produces a [Schema Contract](/concepts/schema-contracts) of that supergraph instead.
The filtering is driven by the `@tag` directives applied to your subgraph schemas.
* `--exclude` removes every schema element tagged with any of the given tags.
* `--include` keeps only the schema elements tagged with any of the given tags, plus the elements required to resolve them.
Both options accept multiple tags and can be combined.
By default, only a contract of the base federated graph will be generated, which can be be disabled by `--disable-base-contract`.
In addition (or alternatively), contract can be generated for specific feature flag names if passed to `--contract-feature-flag-names`.
Only feature flags passed as an argument to this option will generate contracts.
Defining tags but disabling the base contract and not providing any feature flag names will produce an error.
This is the local equivalent of a contract graph created with [`wgc contract create`](/cli/schema-contracts/create).
Use it to test a contract with your router without a control plane connection.
```bash theme={"system"}
npx wgc router compose -i graph.yaml --exclude internal experimental -o router.json
```
Compose a contract that excludes all schema elements tagged `internal` or `experimental`.
```bash theme={"system"}
npx wgc router compose -i graph.yaml --include public -o router.json
```
Compose a contract that includes only the schema elements tagged `public`.
```bash theme={"system"}
npx wgc router compose -i graph.yaml --include public --exclude internal --disable-base-contract --contract-feature-flag-names ff1 ff2 -o router.json
```
Compose a contract for feature flags "ff1" and "ff2" (but not the base federated graph) that includes only the schema elements tagged `public` but excludes any nested schema elements tagged 'internal.
Note: Contract filtering relies on the `@tag` directive. Make sure `@tag` is imported in each subgraph schema that uses it.
## Examples
```bash theme={"system"}
npx wgc router compose -i graph.yaml
```
Compose subgraphs mentioned in the input file graph.yaml
```bash theme={"system"}
npx wgc router compose -i graph.yaml -o router.json
```
Compose subgraphs mentioned in graph.yaml and write it to `router.json`
## Notes
* The `npx wgc router compose` command does not interact with the control plane and completely runs locally.
* When using the `--split-configs-enabled` option, the `--out` is always treated as a directory.
# Download Binary
Source: https://cosmo-docs.wundergraph.com/cli/router/download-binary
Download-binary directly downloads the latest router executable of the appropriate architecture for your system.
## Usage
```bash theme={"system"}
npx wgc router download-binary
```
## Description
The latest available router (see [releases](https://github.com/wundergraph/cosmo/releases?q=router\&expanded=true)) of the appropriate architecture will be downloaded to the directory that is specified. The download contents will appear in a folder named "router". Your `.env` file should be placed adjacent to the executable, which should also contain the paths to your router execution config (and config.yaml, if any). See [router configuration](/router/configuration) for more details.
# Fetch
Source: https://cosmo-docs.wundergraph.com/cli/router/fetch
Fetches the latest valid router execution config of a federated graph.
## Usage
```bash theme={"system"}
npx wgc router fetch production -o router.json
```
## Description
The `npx wgc router fetch` command allows you to fetch the latest valid router execution config of a federated graph from the Cosmo platform's control plane. The config can be piped into a file, which the router can read with the `EXECUTION_CONFIG_FILE_PATH` environment variable or via yaml config
```bash theme={"system"}
execution_config:
file:
# Path to the previous generated file
path: "router.json"
```
## Parameters
* ``: The name of the federated graph for which you want to retrieve the router config.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-o, --out` : Destination file for the router config. Prints to standard output if not provided.
## Examples
Fetch the latest router execution config of the federated graph named "production."
```bash theme={"system"}
npx wgc router fetch production -o router.json
```
Fetch the latest router config of the federated graph named `production` and save it to a file named `router.json`
# Plugin
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin
Commands for working with plugins for the Cosmo Router
WunderGraph Cosmo CLI includes commands for working with plugins for the Cosmo Router.
Scaffold a new router plugin
Build a router plugin
Generate proto and gRPC code for a router plugin
Run tests for a router plugin
Publish a plugin subgraph
Create a plugin subgraph on the control plane
Delete a plugin subgraph from the control plane
For detailed documentation about plugins and how they work, see the [Plugins](/router/gRPC/plugins) documentation.
# Build
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/build
Build a gRPC router plugin
# wgc router plugin build
The `build` command generates gRPC code based on your GraphQL schema and compiles your plugin into platform-specific binaries.
## Usage
```bash theme={"system"}
wgc router plugin build [options] [directory]
```
## Arguments
| Argument | Description | Default |
| - | - | - |
| `directory` | Directory of the plugin | `.` (current directory) |
## Options
| Option | Description | Default |
| - | - | - |
| `--generate-only` | Generate only the proto and mapping files, do not compile the plugin | `false` |
| `--go-module-path ` | Go module path to use for the plugin | `github.com/wundergraph/cosmo/plugin` |
| `--debug` | Build the binary with debug information for use with debuggers | `false` |
| `--platform [platforms...]` | Platform-architecture combinations (e.g., darwin-arm64 linux-amd64) | Host platform |
| `--all-platforms` | Build for all supported platforms | `false` |
| `--skip-tools-installation` | Skip tool installation | `false` |
| `--force-tools-installation` | Force tools installation regardless of version check or confirmation | `false` |
## Description
This command performs several steps to build your plugin:
1. **Detect Plugin Language For Building**: The language of the plugin is detected based on the presence of a go.mod file for Go, if it does not exist we check for a `package.json` file for TyppeScript, if none of these condition match the command fails
2. **Generate Proto and Mapping Files**: Processes your GraphQL schema to generate Protocol Buffers definitions and mapping files
3. **Generate gRPC Code**: Uses the generated Proto files to create Go code for the gRPC service
4. **Install Language Specific Dependencies**: Installs all required dependencies for your plugin
5. **Build Binaries**: Compiles the plugin for one or more platform-architecture combinations
If you only want to generate code but not compile the binary (useful when you're updating your GraphQL schema), you can use the `--generate-only` flag.
## Required Tools
The build command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](/router/gRPC/plugins/debugging) for detailed instructions.
You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:
| Tool | Version | Installation Link |
| - | - | - |
| Go | >=1.22.0 (Last 2 versions) | [Releases](https://go.dev/doc/install) |
| Protocol Buffers (protoc) | ^29.3 | [Releases](https://protobuf.dev/installation/) |
| protoc-gen-go | ^1.34.2 | [GitHub Releases](https://github.com/protocolbuffers/protobuf-go/releases) |
| protoc-gen-go-grpc | ^1.5.1 | [GitHub Releases](https://github.com/grpc/grpc-go/releases) |
| bun | ^1.2.15 | [GitHub Releases](https://github.com/oven-sh/bun/releases) |
When building TypeScript plugins, the protoc TS/JS equivalents of the above are obtained via the `.bin` folder in your plugins `node_modules`, these versions can be customized by the `package.json` of the TS plugin.
## Examples
### Build for the current platform
```bash theme={"system"}
wgc router plugin build ./my-plugin
```
### Generate code only
```bash theme={"system"}
wgc router plugin build --generate-only ./my-plugin
```
### Build for multiple platforms
```bash theme={"system"}
wgc router plugin build --platform darwin-arm64 linux-amd64 ./my-plugin
```
### Build for all supported platforms
```bash theme={"system"}
wgc router plugin build --all-platforms ./my-plugin
```
## Supported Platforms
The following platform-architecture combinations are supported:
| Platform | Description | When to use |
| - | - | - |
| `linux-amd64` | Linux on 64-bit Intel/AMD processors | Most Linux servers, including AWS EC2, Google Cloud, Azure VMs |
| `linux-arm64` | Linux on 64-bit ARM processors | ARM-based servers, AWS Graviton instances, Raspberry Pi 4 |
| `darwin-amd64` | macOS on Intel processors | Intel-based Mac development machines |
| `darwin-arm64` | macOS on Apple Silicon (M1/M2) | Apple Silicon Mac development machines |
| `windows-amd64` | Windows on 64-bit Intel/AMD processors | Windows servers or development machines |
When using the `--all-platforms` flag, binaries for all of the above platforms will be built.
## Output
The build process creates several outputs:
* Generated code in the `generated/` directory
* Compiled binaries and any relevant accompanying files in the `bin/` directory, named according to the target platform (e.g., `my-plugin-darwin-arm64`, `my-plugin-linux-amd64`)
After building, you can configure the Cosmo Router to use your plugin by referencing the appropriate binary in your router configuration.
Ensure that the platform of your built plugin matches the platform where your Cosmo Router runs. For example, if you build your plugin on a Mac (darwin-arm64) but deploy your router on Linux (linux-amd64), you'll need to specify `--platform linux-amd64` during the build process. Using an incompatible plugin binary will result in runtime errors when the router attempts to load the plugin.
See also: [Plugins](/router/gRPC/plugins) · [GraphQL Support for gRPC Integration](/router/gRPC/graphql-support)
# Create
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/create
Creates a federated plugin subgraph on the control plane.
## Usage
A plugin subgraph name must be unique within a namespace.
```bash theme={"system"}
npx wgc router plugin create [pluginName] --label [labelName]
```
After creating a plugin subgraph, you can publish it with [wgc router plugin
publish](/cli/router/plugin/publish).
## Description
The `npx wgc router plugin create` command allows you to create a new plugin subgraph within the Cosmo platform. Plugin subgraphs are specialized GraphQL schemas that extend the functionality of your federated graph through plugins. The `[pluginName]` argument specifies the name of the new plugin subgraph. Use `npx wgc router plugin create -h` to see all the available options.
## **Parameters**
* `[pluginName]`: The name of the plugin subgraph you want to create. It should be a unique identifier (within the namespace) and is used to uniquely identify your plugin subgraph.
## **Options**
* `-n, --namespace` : The namespace of the plugin subgraph (Default: "default").
* `--label`: Assign multiple labels to the new plugin subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project).
* Example: `--label team=A`
* `--readme :` The path to the markdown file which describes the plugin subgraph.
## **Examples**
* Create a new plugin subgraph named "projects" with the label "team=A":
```bash theme={"system"}
npx wgc router plugin create projects --label team=A
```
* Create a new plugin subgraph with a readme file:
```bash theme={"system"}
npx wgc router plugin create projects --label team=infrastructure --readme ./plugin-readme.md
```
* Create a plugin subgraph in a specific namespace:
```bash theme={"system"}
npx wgc router plugin create projects --namespace production --label env=prod
```
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/delete
Deletes a plugin subgraph on the control plane. The plugin subgraph will be deleted from all federated graphs.
## Usage
```bash theme={"system"}
npx wgc router plugin delete [-f, --force]
```
**Delete** is an irreversible action. However, the change will only be visible
to the routers once the composition has been successful. Until then, the
routers will operate with the most recent valid composition. Please use
[subgraph check](/cli/subgraph/check) to understand the impact of your change.
## Description
The `npx wgc router plugin delete` command allows you to delete a plugin subgraph on the Cosmo platform's control plane. When you delete a plugin subgraph, all associated data and configurations will be permanently removed. Use this command with caution, as the action cannot be undone.
## Parameters
* ``: The name of the plugin subgraph you want to delete. This should be the exact name of the plugin subgraph you wish to remove.
## Options
* `-n, --namespace` : The namespace of the plugin subgraph (Default: "default").
* `-f, --force`: An optional flag that allows you to force delete the plugin subgraph without being prompted for confirmation. Use this option if you want to delete the plugin subgraph without additional prompts.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
1. Delete the plugin subgraph named "projects":
```bash theme={"system"}
npx wgc router plugin delete projects
```
2. Force delete the plugin subgraph named "projects" without confirmation:
```bash theme={"system"}
npx wgc router plugin delete projects -f
```
3. Delete a plugin subgraph in a specific namespace:
```bash theme={"system"}
npx wgc router plugin delete projects -n production
```
## Notes
* The `npx wgc router plugin delete` command interacts with the Cosmo platform's control plane to delete the specified plugin subgraph.
* When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental data loss.
* If composition errors occur during deletion, the plugin subgraph will still be deleted, but the router will continue to work with the latest valid schema until the composition issues are resolved.
# Generate
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/generate
Generate proto and gRPC code for a router plugin
# wgc router plugin generate
The `generate` command creates Protocol Buffers definitions, mapping files, and gRPC code based on your GraphQL schema. This command is useful when you want to generate the necessary code without compiling binaries.
## Usage
```bash theme={"system"}
wgc router plugin generate [directory] [options]
```
## Arguments
| Argument | Description | Default |
| - | - | - |
| `directory` | Directory of the plugin | `.` (current directory) |
## Options
| Option | Description | Default |
| - | - | - |
| `--go-module-path ` | Go module path to use for the plugin | `github.com/wundergraph/cosmo/plugin` |
| `--skip-tools-installation` | Skip tool installation | `false` |
| `--force-tools-installation` | Force tools installation regardless of version check or confirmation | `false` |
## Description
This command performs the code generation steps of the plugin build process:
1. **Detect Plugin Language For Generation**: The language of the plugin is detected based on the presence of a go.mod file for Go, if it does not exist we check for a `package.json` file for TyppeScript, if none of these condition match the command fails
2. **Generate Proto and Mapping Files**: Processes your GraphQL schema to generate Protocol Buffers definitions and mapping files
3. **Generate gRPC Code**: Uses the generated Proto files to create Go code for the gRPC service
4. **Install Language Specific Dependencies**: Installs all required dependencies for your plugin
The `generate` command is equivalent to running [`build`](./build) with the `--generate-only` flag. Use this when you're iterating on your GraphQL schema and need to regenerate the code without compiling binaries.
## Required Tools
The generate command will automatically check for and install the necessary toolchain when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
You can also install the dependencies manually and use an IDE with Go / TS support. The following table shows the current versions and download links for the required tools:
| Tool | Version | Installation Link |
| - | - | - |
| Go | >=1.22.0 (Last 2 versions) | [Releases](https://go.dev/doc/install) |
| Protocol Buffers (protoc) | ^29.3 | [Releases](https://protobuf.dev/installation/) |
| protoc-gen-go | ^1.34.2 | [GitHub Releases](https://github.com/protocolbuffers/protobuf-go/releases) |
| protoc-gen-go-grpc | ^1.5.1 | [GitHub Releases](https://github.com/grpc/grpc-go/releases) |
| bun | ^1.0.35 | [GitHub Releases](https://github.com/oven-sh/bun/releases) |
When building TypeScript plugins, the protoc TS/JS equivalents of the above are obtained via the `.bin` folder in your plugins `node_modules`, these versions can be customized by the `package.json` of the TS plugin.
## Examples
### Generate code for the current directory
```bash theme={"system"}
wgc router plugin generate
```
### Generate code for a specific plugin directory
```bash theme={"system"}
wgc router plugin generate ./my-plugin
```
### Generate with a custom Go module path
```bash theme={"system"}
wgc router plugin generate --go-module-path github.com/myorg/my-plugin ./my-plugin
```
### Skip tool installation (useful in CI environments)
```bash theme={"system"}
wgc router plugin generate --skip-tools-installation ./my-plugin
```
## Output
The generate process creates the following outputs:
* **Proto files**: Protocol Buffers definitions in the `generated/` directory
* **Mapping files**: Schema mapping files that connect your GraphQL schema to the gRPC service
* **Generated code**: gRPC client and server code in the language of the plugin in the `generated/` directory
* **Language specific dependencies**: All required dependencies will be installed in your plugin
After generating, you can continue development with your IDE or run [`build`](./build) to compile the plugin into binaries.
# Init
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/init
Scaffold a new gRPC router plugin
# wgc router plugin init
The `init` command scaffolds a new gRPC router plugin project with all the necessary files and directory structure.
## Usage
```bash theme={"system"}
wgc router plugin init [options]
```
## Arguments
| Argument | Description |
| - | - |
| `name` | Name of the plugin |
## Options
| Option | Description | Default |
| - | - | - |
| `-p, --project ` | Project name. When provided, a minimal router project is bootstrapped and the plugin is created at `/`. | (none) |
| `-d, --directory ` | Directory to create the plugin or project in | `.` (current directory) |
| `-l, --language ` | Programming language to use for the plugin (currently only `go` and `ts` is supported) | `go` |
## Description
This command creates a new plugin directory with the specified name and scaffolds the basic plugin structure, including:
* A GraphQL schema file (`src/schema.graphql`)
* Language specific implementation files
* For Go: `src/main.go`, `src/main_test.go`
* For TS: `src/plugin.ts`, `src/plugin.test.ts`
* Generated mapping and protocol files (`generated/mapping.json`, `generated/service.proto`, `generated/service.proto.lock.json`)
* Language specific configuration (`go.mod`)
* For Go: `go.mod`
* For TS: `package.json`, `tsconfig.json`
* Makefile and Dockerfile (`Makefile`, `Dockerfile`)
* Documentation (`README.md`)
When `--project` is provided, a minimal router project is created in the project directory with:
* Router configuration files in the project root (`config.yaml`, `graph.yaml`)
* Project-level files (`README.md`, `Makefile`, `.gitignore`)
* The plugin located at `/`
If you want to create a plugin in an existing project directory, omit `--project` and use `-d/--directory` to choose where the plugin directory should be created.
## Directory Structure
### With `--project`
```text Go theme={"system"}
my-project/
├── README.md # Project documentation
├── Makefile # Project Makefile
├── config.yaml # Router configuration
├── graph.yaml # Supergraph configuration
├── .gitignore
└── my-plugin/ # Your plugin directory
├── README.md
├── Makefile
├── go.mod
├── .gitignore
├── .cursorignore
├── .cursor/
│ └── rules/
│ └── plugin-development.mdc
├── src/
│ ├── schema.graphql
│ ├── main.go
│ └── main_test.go
├── generated/
│ ├── mapping.json
│ ├── service.proto
│ └── service.proto.lock.json
└── Dockerfile
```
```text TypeScript theme={"system"}
my-project/
├── README.md # Project documentation
├── Makefile # Project Makefile
├── config.yaml # Router configuration
├── graph.yaml # Supergraph configuration
├── .gitignore
└── my-plugin/ # Your plugin directory
├── README.md
├── Makefile
├── package.json
├── tsconfig.json
├── .gitignore
├── .cursorignore
├── .cursor/
│ └── rules/
│ └── plugin-development.mdc
├── src/
│ ├── schema.graphql
│ ├── plugin.ts
│ ├── plugin-server.ts
│ └── plugin.test.ts
├── generated/
│ ├── mapping.json
│ ├── service.proto
│ └── service.proto.lock.json
└── Dockerfile
```
### Without `--project`
The plugin is created directly under the chosen directory:
```text Go theme={"system"}
my-plugin/
├── README.md
├── Makefile
├── go.mod
├── .gitignore
├── .cursorignore
├── .cursor/
│ └── rules/
│ └── plugin-development.mdc
├── src/
│ ├── schema.graphql
│ ├── plugin.ts
│ ├── plugin-server.ts
│ └── plugin.test.ts
├── generated/
│ ├── mapping.json
│ ├── service.proto
│ └── service.proto.lock.json
└── Dockerfile
```
```text TypeScript theme={"system"}
my-plugin/
├── README.md
├── Makefile
├── package.json
├── tsconfig.json
├── .gitignore
├── .cursorignore
├── .cursor/
│ └── rules/
│ └── plugin-development.mdc
├── src/
│ ├── schema.graphql
│ ├── main.go
│ └── main_test.go
├── generated/
│ ├── mapping.json
│ ├── service.proto
│ └── service.proto.lock.json
└── Dockerfile
```
## Examples
### Basic usage
```bash theme={"system"}
wgc router plugin init users
```
### Create a new project and plugin
```bash theme={"system"}
wgc router plugin init users -p cosmo
```
### Specify a custom directory
```bash theme={"system"}
wgc router plugin init users -d ./plugins
```
## Next Steps
After initializing your plugin, you should:
1. Customize the GraphQL schema in `src/schema.graphql`
2. Generate code with `wgc router plugin generate` or `make generate`
3. Implement your resolvers in `src/main.go` or `src/plugin.ts`
4. Implement your tests in `src/main_test.go` or `src/plugin.test.ts` and run them with `make test`
5. Build your plugin with `make build`
# Publish
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/publish
Publishes a plugin subgraph on the control plane. If the plugin subgraph doesn't exist, it will be created and the Docker image will be built and pushed to the registry.
## **Usage**
```bash theme={"system"}
npx wgc router plugin publish [directory]
```
**Prerequisites**: Before publishing, you must first scaffold your plugin using `npx wgc router plugin init ` to create the required directory structure and files.
**Publish** is an irreversible action. However, the change will only be
visible to the routers once the composition has been successful. Until then,
the routers will operate with the most recent valid composition. Please use
[subgraph check](/cli/subgraph/check) to understand the impact of your change.
## **Description**
The `npx wgc router plugin publish` command enables you to publish a plugin subgraph to the Cosmo platform. Publishing a plugin subgraph makes it available for use by federated graphs, allowing them to extend functionality through custom plugins. The command builds and pushes a Docker image containing your plugin to the registry, then publishes the subgraph schema to the control plane.
The command expects a specific directory structure for your plugin and automatically locates the necessary files within the plugin directory. The plugin name is derived from the directory name. You should first run `npx wgc router plugin init ` to scaffold the proper directory structure.
## **Parameters**
* `[directory]`: The path to the plugin directory (optional, defaults to current directory). The plugin name is automatically derived from the directory name.
## **Options**
### **Plugin Directory Structure**
The plugin directory must contain the following files in their expected locations (created automatically by `npx wgc router plugin init`):
* `src/schema.graphql`: The GraphQL schema definition for your plugin
* `Dockerfile`: The Dockerfile that defines how to build the plugin container image
* `generated/service.proto`: The protocol buffer schema file
* `generated/mapping.json`: The protocol buffer mapping file
* `generated/service.proto.lock.json`: The protocol buffer lock file
### **Optional Options**
If the plugin subgraph has already been created previously, the `label`
parameter will be ignored. Use [subgraph update](/cli/subgraph/update) to
update these values.
* `--name [string]`: The name of the plugin subgraph. If not provided, the name will
be derived from the directory name.
* `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
* `--platform [platforms...]`: The platforms used to build the Docker image. Pass multiple platforms separated by spaces. Supported formats: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`. Defaults to `linux/amd64` and includes your current platform if supported.
* Example: `--platform linux/amd64 linux/arm64`
* `--label [labels...]`: Assign multiple labels to the new plugin subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project). The labels are passed in the format `=`.
* Example: `--label team=backend --label environment=production`
If you are *creating* a plugin subgraph for the first time with `router plugin publish`, the `label` parameter can be used to set labels. Note that a subgraph will only be considered for a federated graph composition if the subgraph's labels match the labels matcher of that federated graph.
If you are not creating a plugin subgraph for the first time, the `label` parameter will be ignored. To update the labels of an existing plugin subgraph, use [subgraph update](/cli/subgraph/update).
* `--fail-on-composition-error`: If set, the command will fail if the composition of the federated graph fails.
* `--fail-on-admission-webhook-error`: If set, the command will fail if the admission webhook fails.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## **Examples**
### Publish a plugin subgraph
```bash theme={"system"}
npx wgc router plugin publish ./plugins/my-plugin
```
### **Create and publish a plugin subgraph with labels and multi-platform support**
```bash theme={"system"}
npx wgc router plugin publish ./plugins/my-plugin \
--label team=backend --label environment=production \
--platform linux/amd64 linux/arm64
```
### **Publish with custom name**
If the plugin name is not provided, the name will be derived from the
directory name. This is mainly used to publish plugin feature subgraphs, as
the directory will still be the base subgraph.
```bash theme={"system"}
npx wgc router plugin publish ./plugins/my-plugin \
--name my-custom-name
```
### **Publish with custom namespace**
```bash theme={"system"}
npx wgc router plugin publish ./plugins/my-plugin \
--namespace production
```
## **Typical Workflow**
Here's the recommended workflow for developing and publishing a plugin:
1. **Initialize the plugin**:
```bash theme={"system"}
npx wgc router plugin init my-plugin
```
This creates the plugin in the `plugins/my-plugin/` directory.
2. **Develop your plugin**: Modify the generated files as needed:
* Edit `src/schema.graphql` to define your GraphQL schema
* Implement your plugin logic in `src/main.go`
* Update the `Dockerfile` if needed for custom build requirements
3. **Test your plugin locally**: Use the generated `Makefile` commands to build and test
4. **Publish the plugin**:
```bash theme={"system"}
# Option 1: Specify the directory path
npx wgc router plugin publish ./plugins/my-plugin
# Option 2: Run from within the plugin directory
cd ./plugins/my-plugin
npx wgc router plugin publish
```
## **Docker Requirements**
Docker Buildx with a container builder is required for publishing plugins.
### Recommended Installation
* **macOS**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [OrbStack](https://orbstack.dev/)
* **Windows**: [Docker Desktop](https://www.docker.com/products/docker-desktop/)
* **Linux**: [Docker Engine](https://docs.docker.com/engine/install/)
Before publishing plugins, ensure you have:
* Docker Buildx enabled
* A container builder configured
To verify your setup, run:
```bash theme={"system"}
docker buildx version
docker buildx inspect
```
**Important:** The `docker buildx inspect` output must show the `docker-container` driver. If you don't see this, create a builder:
```bash theme={"system"}
docker buildx create --name container-builder --use
docker buildx inspect --bootstrap
```
## **Build Process**
The publish command performs the following steps:
1. **Validation**: Validates that all required files exist in the plugin directory at their expected locations
2. **Image Build**: Builds the Docker image using `docker buildx build` with the specified platforms
3. **Image Push**: Pushes the built image to the plugin registry
4. **Schema Publish**: Publishes the GraphQL schema to the control plane
## **Notes**
* The `npx wgc router plugin publish` command interacts with the Cosmo platform's control plane to publish the specified plugin subgraph and builds a Docker image that gets pushed to the plugin registry.
* Ensure that Docker is installed and running on your system, as the command builds and pushes Docker images as part of the publication process.
* The command expects a specific directory structure with files in predetermined locations. Make sure your plugin follows this structure (created by running `npx wgc router plugin init `):
```
my-plugin/
├── src/
│ └── schema.graphql
├── generated/
│ ├── service.proto
│ ├── mapping.json
│ └── service.proto.lock.json
└── Dockerfile
```
* The plugin name is automatically derived from the directory name (e.g., if your plugin is in `./plugins/my-awesome-plugin`, the plugin name will be `my-awesome-plugin`).
* If the build process fails at any step, the command will exit with an error and provide details about what went wrong.
# Test
Source: https://cosmo-docs.wundergraph.com/cli/router/plugin/test
Run tests for a gRPC router plugin
# wgc router plugin test
The `test` command runs tests for your gRPC router plugin to verify its functionality.
## Usage
```bash theme={"system"}
wgc router plugin test [options] [directory]
```
## Arguments
| Argument | Description | Default |
| - | - | - |
| `directory` | Directory of the plugin | `.` (current directory) |
## Options
| Option | Description | Default |
| - | - | - |
| `--skip-tools-installation` | Skip tool installation | `false` |
| `--force-tools-installation` | Force tools installation regardless of version check or confirmation | `false` |
## Description
This command runs the tests for your plugin. For Go plugins, it executes the Go test runner against the test files in your source directory.
The test command will:
1. Check and install required tools if needed
2. Run the tests in the `src` directory
3. Report the test results
Testing your plugin is an important step to ensure that your resolvers work correctly before deploying the plugin to your router.
## Required Tools
The build command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](/router/gRPC/plugins/debugging) for detailed instructions.
You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:
| Tool | Version | Installation Link |
| - | - | - |
| Go | >=1.22.0 (Last 2 versions) | [Releases](https://go.dev/doc/install) |
| Protocol Buffers (protoc) | ^29.3 | [Releases](https://protobuf.dev/installation/) |
| protoc-gen-go | ^1.34.2 | [GitHub Releases](https://github.com/protocolbuffers/protobuf-go/releases) |
| protoc-gen-go-grpc | ^1.5.1 | [GitHub Releases](https://github.com/grpc/grpc-go/releases) |
| bun | ^1.2.15 | [GitHub Releases](https://github.com/oven-sh/bun/releases) |
When building TypeScript plugins, the protoc TS/JS equivalents of the above are obtained via the `.bin` folder in your plugins `node_modules`, these versions can be customized by the `package.json` of the TS plugin.
## Test File
When you initialize a new plugin with `wgc router plugin init`, a test file is automatically created at `src/main_test.go`. This file includes a basic test setup that you can expand with your own test cases.
The default test file tests the plugin's ability to handle basic GraphQL queries. You should add additional tests to cover your custom resolver logic.
## Examples
### Run tests for a plugin
```bash theme={"system"}
wgc router plugin test ./my-plugin
```
## Best Practices
When writing tests for your router plugin:
1. **Test all resolvers**: Make sure to create test cases for all your GraphQL resolvers
2. **Test edge cases**: Include tests for error conditions and edge cases
3. **Mock dependencies**: If your plugin interacts with external systems, use mocks in your tests
4. **Test arguments**: Verify that your resolvers correctly handle different argument values
5. **Benchmark performance**: Add benchmarks for performance-critical resolvers
By thoroughly testing your plugin, you can ensure it behaves correctly when integrated with the Cosmo Router.
See also: [Plugins](/router/gRPC/plugins) · [GraphQL Support for gRPC Integration](/router/gRPC/graphql-support)
# Token
Source: https://cosmo-docs.wundergraph.com/cli/router/token
# Create
Source: https://cosmo-docs.wundergraph.com/cli/router/token/create
Creates a token scoped to a federated graph. The token permits the router to communicate with the platform and to export metrics to the collectors.
## Usage
```bash theme={"system"}
npx wgc router token create -g
```
## Description
The `npx wgc router token create` command creates a new token for a federated graph. The token can be used to authenticate against the control plane from the routers.
## Parameters
* ``: The name of the token to create. Only serves as a reference for the user.
## Required Options
```bash theme={"system"}
-g , --graph-name
```
The name of the federated graph that the token should be created for.
## Options
`-n, --namespace` : The namespace of the federated graph (Default: "default").
## Examples
```bash theme={"system"}
npx wgc router token create graphToken -g production
```
Create a new token named "graphToken" for the federated graph named "production". The token is displayed once in the CLI. Pass the token as an environment variable to the router [configuration](/router/configuration).
## Notes
* The token is only valid for a specific federated graph.
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/router/token/delete
Deletes a token of a federated graph.
## Usage
```bash theme={"system"}
npx wgc router token delete -g
```
## Description
The `npx wgc router token delete` command deletes a token of a federated graph.
## Parameters
* ``: The name of the token to be deleted.
## Required Options
```bash theme={"system"}
-g , --graph-name
```
The name of the federated graph that the token should be deleted from.
## Options
`-n, --namespace` : The namespace of the federated graph (Default: "default").
## Examples
```bash theme={"system"}
npx wgc router token delete graphToken -g production
```
Deletes a token named "graphToken" of the federated graph named "production".
# List
Source: https://cosmo-docs.wundergraph.com/cli/router/token/list
Lists router tokens of a federated graph. Only shows metadata not the actual token.
## Usage
```bash theme={"system"}
npx wgc router token list
```
## Description
The `npx wgc router token list` command lists all the tokens of a federated graph.
## Parameters
* ``: The name of the federated graph.
## Options
`-n, --namespace` : The namespace of the federated graph (Default: "default").
## Examples
```bash theme={"system"}
npx wgc router token list production
```
Lists all the tokens of the federated graph named "production" within the *default* namespace.
# Schema Contracts
Source: https://cosmo-docs.wundergraph.com/cli/schema-contracts
Schema contracts helps you provide filtered out versions of your composed graph to different customers.
For detailed information, please refer to [this](/studio/schema-contracts) page.
# Create
Source: https://cosmo-docs.wundergraph.com/cli/schema-contracts/create
Creates a contract from a federated graph or monograph.
To delete a contract, please use [federated-graph delete](/cli/federated-graph/delete).
## Usage
#### Exclude (the items that have the tag(s) specified will be removed from the federated graph)
By default, all top-level nodes will be included in the schema unless explicitly excluded.
```bash theme={"system"}
npx wgc contract create --source --exclude internal -r
```
#### Include (the items that have the tag(s) specified will be included in the federated graph)
Child nodes inherit inclusion from their parent unless explicitly excluded.
For example, an included Object would include all its field unless explicitly excluded.
Similarly, an included field would include all its field arguments unless explicitly excluded.
By default, no top-level nodes will be included in the schema unless explicitly included.
Child nodes inherit inclusion from their parents unless explicitly excluded.
```bash theme={"system"}
npx wgc contract create --source --include public -r
```
#### Include and exclude together
##### Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.126.2](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.126.2) |
The include and exclude tag sets must be mutually exclusive.
If the same tag is added to both the include and exclude sets, an error will be returned.
If both include and exclude tags are provided, the behaviour is thus:
1. The schema starts blank (no nodes)
2. Top-level (parent) nodes (Enums, Inputs, Interfaces, Objects, Scalars, and Unions) are included if they define a
specified tag to include.
3. Child-level nodes (Enum values, Input fields, Interface fields, Object fields) are also included unless
the child defines a specified tag to exclude.
4. Argument nodes (Object field arguments and Interface field arguments) are included if the corresponding field is
included unless the field argument defines a specified tag to exclude.
```bash theme={"system"}
npx wgc contract create --source --include public --exclude internal -r
```
## Description
The `npx wgc contract create` command allows you to create a contract from a federated graph or monograph by providing
tags to exclude from the schema.
This will create a new contract graph linked to the source graph.
## Parameters
* ``: The name of the contract graph you want to create.
## Required Options
`-r , --routing-url`: The routing URL of your router. This URL defines the endpoint where the router will be accessible.
The contract graph will be accessible through this router.
`--source`: The name of the source graph from which contract is created.
## Options
* `-n, --namespace` : The namespace of the contract graph and source graph (Default: "default").
* `--exclude` : The list of tags that need to be excluded from the source graph schema.
* `--include` : The list of tags that need to be included from the source graph schema.
* `--admission-webhook-url ` the base url of the admission webhook.
This is the url that the controlplane will use to implement admission control for the contract graph.
Example: `https://admission.example.com` (without the `/validate-config` path name)
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url.
The header containing this signature is `X-Cosmo-Signature-256`
* `--readme` : The markdown file which describes the contract graph.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
Create a contract graph named `production-external` from the source graph schema of `production` that excludes all
schema elements tagged with `internal` or `experimental`:
```bash theme={"system"}
npx wgc contract create production-external --source production --exclude internal experimental -r http://router.example.com/graphql
```
Create a contract graph named `production-external` from the source graph schema of `production` that includes all
schema elements tagged with `public` or `api`:
```bash theme={"system"}
npx wgc contract create production-external --source production --include public api -r http://router.example.com/graphql
```
Create a contract graph named `public-api` from the source graph schema of `supergraph` that includes all
schema elements tagged with `core` or `api` and excludes all schema elements tagged with `classified` or `internal`:
```bash theme={"system"}
npx wgc contract create public-api --source supergraph --include core api --exclude classified internal -r http://router.example.com/graphql
```
# Delete, List, Fetch And More
Source: https://cosmo-docs.wundergraph.com/cli/schema-contracts/delete-list-fetch-and-more
Since a contract graph is fundamentally a federated graph, all commands and operations applicable to federated graphs can also be used with contract graphs. However, be mindful of certain [caveats](/studio/schema-contracts#caveats-to-remember) specific to working with contract graphs to ensure correct functionality and avoid potential issues.
# Update
Source: https://cosmo-docs.wundergraph.com/cli/schema-contracts/update
This command updates the tag filters for the contract. To update other aspects of the contract graph please use the federated-graph or monograph update commands.
To delete a contract, please use [federated-graph delete](/cli/federated-graph/delete).
## Usage
#### Exclude (the items that have the tag(s) specified will be removed from the source federated graph)
By default, all top-level nodes will be included in the schema unless explicitly excluded.
```bash theme={"system"}
npx wgc contract update --source --exclude internal
```
#### Include (the items that have the tag(s) specified will be included in the source federated graph)
Child nodes inherit inclusion from their parent unless explicitly excluded.
For example, an included Object would include all its field unless explicitly excluded.
Similarly, an included field would include all its field arguments unless explicitly excluded.
By default, no top-level nodes will be included in the schema unless explicitly included.
Child nodes inherit inclusion from their parents unless explicitly excluded.
```bash theme={"system"}
npx wgc contract update --source --include public
```
#### Include and exclude together
##### Minimum Requirements
| Package | Minimum version |
| - | - |
| [wgc](/cli/intro) | [0.126.2](https://github.com/wundergraph/cosmo/releases/tag/wgc%400.126.2) |
The include and exclude tag sets must be mutually exclusive.
If the same tag is added to both the include and exclude sets, an error will be returned.
If both include and exclude tags are provided, the behaviour is thus:
1. The schema starts blank (no nodes)
2. Top-level (parent) nodes (Enums, Inputs, Interfaces, Objects, Scalars, and Unions) are included if they define a
specified tag to include.
3. Child-level nodes (Enum values, Input fields, Interface fields, Object fields) are also included unless
the child defines a specified tag to exclude.
4. Argument nodes (Object field arguments and Interface field arguments) are included if the corresponding field is
included unless the field argument defines a specified tag to exclude.
```bash theme={"system"}
npx wgc contract update --source --include public --exclude internal
```
## Description
The `npx wgc contract update` command allows you to update the tag filters for the contract.
This will result in overwriting existing ones and causes a recomposition of the contract graph.
## Parameters
* ``: The name of the contract graph you want to update.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `--exclude` : The list of tags that should be excluded from the source graph schema.
* `--include` : The list of tags that should be included from the source graph schema.
* `-r , --routing-url`: The routing URL of your router.
This URL defines the endpoint where the router will be accessible.
The contract graph will be accessible through this router.
* `--admission-webhook-url ` the base url of the admission webhook.
This is the url that the controlplane will use to implement admission control for the contract graph.
Example: `https://admission.example.com` (without the `/validate-config` path name)
* `--admission-webhook-secret`: Allows you to sign requests (HMAC) made to your admission webhook url.
The header containing this signature is `X-Cosmo-Signature-256`
* `--readme` : The markdown file which describes the contract graph.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
Updates a contract graph named `production-external` with the new exclude tags: `experimental` and `deprecated`:
```bash theme={"system"}
npx wgc contract update production-external --exclude experimental deprecated
```
Updates a contract graph named `production-external` with the new include tags: `public` and `api`:
```bash theme={"system"}
npx wgc contract update production-external --include public api
```
Updates a contract graph named `public-api` with the new include tags `core` and `api` and the new exclude tags `classified` and `internal`:
```bash theme={"system"}
npx wgc contract update public-api --include core api --exclude classified internal
```
# Subgraph
Source: https://cosmo-docs.wundergraph.com/cli/subgraph
Subgraphs are the building blocks of a federated graph. Each subgraph in a Federated GraphQL Architecture is responsible for defining its own part of the schema and handling the corresponding queries.
Before you can interact with a subgraph, you need to [`create`](/cli/subgraph/create) it. Each subgraph is mapped to a GraphQL service that can respond to the relevant GraphQL schema.
# Batch Publish
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/batch-publish
Publishes the schemas of multiple existing subgraphs in a single request using a config file.
## **Usage**
```bash theme={"system"}
npx wgc subgraph batch-publish --config [configFilePath] --namespace [namespace]
```
**Batch publish** is an irreversible action. Changes become visible to the routers only after composition succeeds. Until then, the routers operate with the most recent valid composition. Use [subgraph check](/cli/subgraph/check) to understand the impact of your changes first.
## **Description**
The `npx wgc subgraph batch-publish` command publishes new schemas for several subgraphs in one command. List the subgraphs and their schema files in a config file, and they are published together. Use this when you update multiple subgraphs at the same time instead of running [subgraph publish](/cli/subgraph/publish) for each one.
Every subgraph and feature subgraph listed in the config must already exist in the namespace. If any does not exist, the command fails and reports the missing names without publishing anything. Regular subgraphs and feature subgraphs go in the same `subgraphs` list.
Batch publish does not create subgraphs and does not publish plugin or gRPC service subgraphs. Use [subgraph create](/cli/subgraph/create) to create a subgraph, [subgraph publish](/cli/subgraph/publish) to create and publish in one step, [router plugin publish](/cli/router/plugin/publish) for plugins, and [grpc-service publish](/cli/grpc-service/publish) for gRPC services.
## **Config file**
The config file is YAML. It contains a `subgraphs` list, where each entry has a `name` and a `schema` file path. Schema paths are resolved relative to the config file.
```yaml theme={"system"}
subgraphs:
- name: products
schema: ./subgraphs/products.graphql
- name: reviews
schema: ./subgraphs/reviews.graphql
# Feature subgraphs are listed here too; they are detected automatically.
- name: products-feature
schema: ./subgraphs/products-feature.graphql
```
## **Options**
* `-c, --config`: The path to the YAML config file listing the subgraphs to publish. Required.
* Example: `--config ./batch-publish.yaml`
* `-n, --namespace`: The namespace of the subgraphs (Default: "default").
* `--fail-on-composition-error`: If set, the command fails if the composition of any federated graph fails.
* `--fail-on-admission-webhook-error`: If set, the command fails if the admission webhook fails.
* `--suppress-warnings`: Suppresses any warnings produced by composition.
* `--disable-resolvability-validation`: Disables the validation for whether all nodes of the federated graph are resolvable. Do not use unless troubleshooting.
* `-l, --limit `: The maximum number of entries to display for each category of results, such as composition errors, composition warnings, and deployment errors. Defaults to `50`.
## **Example**
```bash theme={"system"}
npx wgc subgraph batch-publish --config ./batch-publish.yaml --namespace production
```
## **Notes**
* All subgraphs and feature subgraphs in the config must already exist. A missing subgraph fails the entire request and nothing is published.
* Schema file paths in the config are resolved relative to the config file location.
* Composition and deployment errors are reported per federated graph. Graphs that compose successfully are still deployed, matching the behavior of [subgraph publish](/cli/subgraph/publish).
# Check
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/check
Checks for breaking changes and composition errors for all the connected federated graphs.
## Usage
### Check schema changes
```bash theme={"system"}
npx wgc subgraph check --schema
```
Use this command whenever you make modifications to your subgraphs. It will report any GraphQL or composition errors before they land on production. The report will be made visible under [Schema Checks](/studio/schema-checks).
### Check deletion of a subgraph
```bash theme={"system"}
npx wgc subgraph check --delete
```
This command will check any breaking changes or composition errors in case the subgraph is deleted.
### Check how a new subgraph affects the federated graph
```bash theme={"system"}
# There are two ways to check the impact of a new subgraph:
# 1. Create the subgraph and check the impact
npx wgc subgraph create products --label team=A --routing-url http://localhost:4001/graphql
npx wgc subgraph check --schema schema.graphql
# 2. Check the impact without creating the subgraph
npx wgc subgraph check --schema schema.graphql --label team=A
```
## Description
The `npx wgc subgraph check` command checks for breaking changes and composition errors in all connected federated graphs associated with the specified subgraph. This validation process ensures that the new schema you intend to use does not introduce any issues that could negatively impact existing federated graphs.
This command also checks feature subgraphs. Pass its name to validate the proposed schema against the feature flag compositions that include it. See [Schema Checks](/studio/schema-checks#feature-subgraphs-and-feature-flags). Composition errors, composition warnings, and composed breaking changes include a `FEATURE_FLAG` column identifying the feature flag each entry belongs to (empty for the base supergraph).
## Parameters
* ``: The name of the subgraph for which you want to perform the validation check. This should be the exact name of the subgraph you wish to check.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `--schema `: The path to the new schema file that you want to validate. This file should contain the complete schema definition in the GraphQL Schema Definition Language (SDL) format.
* `--delete`: Check for breaking changes and composition errors in case the subgraph will be deleted.
* `--skip-traffic-check` : This will skip checking against client traffic and any breaking change will fail the run.
* `-j, --json`: Prints the check result in JSON format instead of table output. Useful for CI/CD automation and scripts.
* `-o, --out [string]`: Writes the JSON check result to a destination file. This option enables JSON output automatically.
* `--label [labels...]`: The labels to apply to the new subgraph. The labels are passed in the format `= =`. This parameter is always ignored if the subgraph already exists.
* `--disable-resolvability-validation`: This flag disables the validation for whether all nodes of the federated graph are resolvable. Do not use unless troubleshooting.
* `-l, --limit [number]`: The maximum number of entries to display for each category of results, such as schema changes, composed schema breaking changes, composition errors, composition warnings, lint issues, and graph pruning issues. Defaults to `50`.
The check command requires either the `--schema` or `--delete` parameter.
## Examples
1. Check for breaking changes and composition errors for the subgraph "products" with the new schema file located at "./schemas/new\_schema.graphql":
```bash theme={"system"}
npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql
```
2. Check for breaking changes and composition errors for the subgraph which does not exist yet:
```bash theme={"system"}
npx wgc subgraph check newSubgraph -n default --schema ./schemas/new_schema.graphql --label team=A
```
3. Output the check result as JSON for automation:
```bash theme={"system"}
npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql --json
```
4. Write the JSON check result to a file:
```bash theme={"system"}
npx wgc subgraph check products -n default --schema ./schemas/new_schema.graphql --out ./check-result.json
```
The labels should match the labels of the federated graph you want to check against.
## Sample output with changes and errors
Changes
| CHANGE | TYPE | DESCRIPTION | BREAKING |
| - | - | - | - |
| BREAKING | FIELD\_REMOVED | Field 'email' was removed from object type 'User' | |
| NON-BREAKING | FIELD\_ADDED | Field 'emailID' was added to object type 'User' | |
Composition Errors
| FEDERATED\_GRAPH\_NAME | ERROR\_MESSAGE |
| - | - |
| inventory | Type "Product" is an extension type, but there is no type definition for "Product" in any subgraphs. |
1. Check for breaking changes and composition errors for the subgraph "products" with the new schema file located at "./schemas/new\_schema.graphql":
```bash theme={"system"}
npx wgc subgraph check employees --delete
```
### Sample output
Changes
| CHANGE | TYPE | DESCRIPTION | BREAKING |
| - | - | - | - |
| BREAKING | TYPE\_REMOVED | Type 'Department' was removed | |
| NON-BREAKING | TYPE\_REMOVED | Type 'RoleType' was removed | |
Composition Errors
| FEDERATED\_GRAPH\_NAME | ERROR\_MESSAGE |
| - | - |
| inventory | The subgraph "products" could not be federated for the following reason:
The object type "Employee" defines the directive "@override(from: "employees)" on the following field: "notes".
The required "from" argument of type "String!" must be provided with an existing subgraph name.
However, a subgraph by the name of "employees" does not exist. |
## VCS Context
If you want to associate custom information with the checks being performed, you can do so by setting the following environment variables:
* `COSMO_VCS_AUTHOR`: The author's email address associated with the commit (e.g: `foo@bar.com`).
* `COSMO_VCS_COMMIT`: The specific commit hash for the changes you are testing (e.g: `de233ddwqedqwe`).
* `COSMO_VCS_BRANCH`: The branch name where the commit resides (e.g: `main`).
```bash theme={"system"}
export COSMO_VCS_AUTHOR=foo@bar.com
export COSMO_VCS_COMMIT=de233ddwqedqwe
export COSMO_VCS_BRANCH=main
```
## Usage in CI and GitHub Integration
Checkout the tutorial [here](/tutorial/pr-based-workflow-for-federation) on how to use the subgraph check command in CI with GitHub.
## Notes
* The `npx wgc subgraph check` command interacts with the Cosmo platform's control plane and connected federated graphs to perform the validation checks.
* If there are no breaking changes or composition errors detected, the tables will be empty, indicating that the new schema is compatible with the existing federated graphs.
# Create
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/create
Creates a federated subgraph on the control plane.
## Usage
A subgraph name must be unique within a namespace.
```bash theme={"system"}
npx wgc subgraph create [subgraphName] --label [labelName] --routing-url [url]
```
After creating a subgraph, you can publish it with [wgc subgraph publish](/cli/subgraph/publish).
## Description
The `npx wgc subgraph create` command allows you to create a new subgraph within the Cosmo platform. Subgraphs are isolated GraphQL schemas that can be independently deployed and managed, providing modularity and scalability to your GraphQL APIs. The `[subgraphName]` argument specifies the name of the new subgraph, while the `--label` and `--routing-url` options allow you to add custom metadata and define the endpoint for the subgraph's data. Use `npx wgc subgraph create -h` to see all the available options.
## **Parameters**
* `[subgraphName]`: The name of the subgraph you want to create. It should be a unique (within the namespace) and descriptive identifier for the new subgraph.
## **Options**
* `-n, --namespace` : The namespace of the subgraph (Default: "default").
* `--edg, --event-driven-graph`: Irreversibly define the subgraph as an [Event-Driven Graph](/federation/event-driven-federated-subscriptions). If the subgraph is intended to be a regular subgraph, do not use this flag. Attempting to set `routing-url`, `subscription-url`, `subscription-protocol`, or `websocket-subprotocol` when this flag is set will produce an error.
* `--label`: Assign multiple labels to the new subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project).
* Example: `--label team=A`
* `--routing-url`: Set the URL for the subgraph's data source. This URL defines the endpoint where the subgraph will fetch data from. Will produce an error if the `-edg` flag is set.
* Example: `--routing-url http://localhost:4001/graphql`
* `--subscription-url:` Optionally, use a different URL for subscription requests. If no subscription URL is provided, the above routing URL is used for subscriptions. Will produce an error if the `-edg` flag is set.
* `--subscription-protocol:` Optionally, set a protocol to use for subscriptions. Will produce an error if the `-edg` flag is set. The available options are:
* `ws` (default): Negotiate an appropriate protocol over websockets. Both `graphql-ws` and `subscription-transport-ws` are supported.
* `sse`: Use Server-Sent Events with a GET request.
* `sse_post`: Use Server-Sent events with a POST request.
* `--readme :` The path to the markdown file which describes the subgraph.
* `--websocket-subprotocol:` The subprotocol to use when subscribing to the subgraph. Will produce an error if the `-edg` flag is set. The supported protocols are `auto (default)`, `graphql-ws`, and `graphql-transport-ws`. It should be used only if the subscription protocol is `ws`.
## **Examples**
### Regular subgraph
* Create a new subgraph named "products" with the label "team=A" and the routing URL "[http://localhost:4001/graphql](http://localhost:4001/graphql)":
```bash theme={"system"}
npx wgc subgraph create products --label team=A --routing-url http://localhost:4001/graphql
```
### Event-Driven Graph
* Create a new Event-Driven Graph named "events" with the label "team=A":
```bash theme={"system"}
npx wgc subgraph create events --label team=A --edg
```
# Delete
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/delete
Deletes a subgraph on the control plane. The subgraph will be deleted from all federated graphs.
## Usage
```bash theme={"system"}
npx wgc subgraph delete [-f, --force]
```
**Delete** is an irreversible action. However, the change will only be visible to the routers once the composition has been successful. Until then, the routers will operate with the most recent valid composition. Please use [subgraph check](/cli/subgraph/check) to understand the impact of your change.
## Description
The `npx wgc subgraph delete` command allows you to delete a subgraph on the Cosmo platform's control plane. When you delete a subgraph, all associated data and configurations will be permanently removed. Use this command with caution, as the action cannot be undone.
## Parameters
* ``: The name of the subgraph you want to delete. This should be the exact name of the subgraph you wish to remove.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-f, --force`: An optional flag that allows you to force delete the subgraph without being prompted for confirmation. Use this option if you want to delete the subgraph without additional prompts.
* `--suppress-warnings`: This flag suppresses any warnings produced by composition.
## Examples
1. Delete the subgraph named "products":
```bash theme={"system"}
npx wgc subgraph delete products
```
2. Force delete the subgraph named "users" without confirmation:
```bash theme={"system"}
npx wgc subgraph delete users -f
```
## Notes
* The `npx wgc subgraph delete` command interacts with the Cosmo platform's control plane to delete the specified subgraph.
* When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental data loss.
# Fetch
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/fetch
Fetches the latest published SDL of a subgraph. If the federated graph is specified, the latest successfully composed version of the subgraph will be fetched.
## Usage
```bash theme={"system"}
npx wgc subgraph fetch
```
## Description
The `npx wgc subgraph fetch` command allows you to fetch the latest Schema Definition Language (SDL) of a subgraph graph from the Cosmo platform's control plane. The fetched SDL represents the last schema of the subgraph graph. You can pass the name of the federated graph to fetch the latest successfully composed subgraph schema from the controlplane.
## Parameters
* ``: The name of the subgraph graph you want to fetch. Replace `` with the name of the subgraph graph you wish to retrieve the SDL for.
## Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `-g --graph-name`: The name of the federated graph to fetch the latest valid subgraph SDL from.
* `-o, --out` : Destination file for the SDL. Prints to standard output if not provided.
## Examples
```bash theme={"system"}
npx wgc subgraph fetch products
```
Fetch the latest SDL of the subgraph graph named "products."
```bash theme={"system"}
npx wgc subgraph fetch products -g mygraph -n default
```
Fetch the latest successfully composed SDL of the subgraph graph named "products" in the "default" namspace.
## Notes
* The `npx wgc subgraph fetch` command interacts with the Cosmo platform's control plane to fetch the SDL. Ensure that you have the necessary permissions to perform this operation.
# Fix
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/fix
Checks for composition errors across all connected federated graphs and tries to fix them through OpenAI integration.
### Usage
```bash theme={"system"}
npx wgc subgraph fix --schema --out-schema
```
### Description
The `npx wgc subgraph fix` command checks for composition errors in all connected federated graphs associated with the specified subgraph and then tries to fix those errors. The output of the fix can be written to the file path provided.
### Parameters
* ``: The name of the subgraph for which you want to perform the fix. This should be the exact name of the subgraph you wish to check.
### Required Options
* `--schema `: The path to the new schema file that you want to validate and then fix its errors. This file should contain the complete schema definition in the GraphQL Schema Definition Language (SDL) format.
### Options
* `-n, --namespace` : The namespace of the federated graph (Default: "default").
* `--out-schema `: The path where the fixed schema file should be written.
## **Example**
* Fix the "products" subgraph using the schema file located at "../demo/subgraphs/products/products.graphql" and write the output of the fix to a file located at "../demo/subgraphs/products/products-fix.graphql".
```bash theme={"system"}
npx wgc subgraph fix products --schema ../demo/subgraphs/products/products.graphql --out-schema ../demo/subgraphs/products/products-fix.graphql
```
### Notes
* The `npx wgc subgraph fix` command interacts with the Cosmo platform's control plane and connected federated graphs to perform the composition checks and then fix them.
* The output of the fix can be written to the path provided to the `--out-schema` option.
# Introspect
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/introspect
Introspects a subgraph.
## Usage
```bash theme={"system"}
npx wgc subgraph introspect --routing-url [url] --header [headers...]
```
## Description
The `npx wgc subgraph introspect` command allows you to introspect a subgraph and returns the schema of the subgraph.
## **Options**
* `--routing-url`: Set the URL for the subgraph's data source. This URL defines the endpoint where the subgraph will fetch data from.
* Example: `--routing-url http://localhost:4001/graphql`
* `--header`: The headers to apply when the subgraph is introspected. This is used for authentication and authorization. The headers are passed in the format \=\ \=\. Use quotes if there exists space in the key/value.
* Example: `--header Authorization='Bearer '`
* `-o, --out` : Destination file for the SDL. Prints to standard output if not provided.
## **Example**
1. Introspect a subgraph with routing URL "[http://localhost:4001/graphql](http://localhost:4001/graphql)":
```bash theme={"system"}
npx wgc subgraph introspect --routing-url http://localhost:4001/graphql
```
# Link
Source: https://cosmo-docs.wundergraph.com/cli/subgraph/link
Links a subgraph to another subgraph on the control plane for schema validation.
## Usage
```bash theme={"system"}
npx wgc subgraph link --target-subgraph /