How do I install the Cosmo CLI?

Run npm install -g wgc@latest to install globally. Node.js LTS is required. You can also run without installation using npx -y wgc@latest.

How does the CLI authenticate?

Set the COSMO_API_KEY environment variable to your API key. For self-hosted control planes, also set COSMO_API_URL.

What does wgc subgraph check do?

It validates the schema change against all connected federated graphs for composition errors and analyzes breaking changes against real client traffic patterns.

How do I deploy a schema change?

Run wgc subgraph publish --schema schema.graphql. The federated graph recomposes automatically with the new schema.

Can I use the CLI behind a corporate proxy?

Yes. From wgc v0.63.0, set the HTTPS_PROXY or HTTP_PROXY environment variable to your proxy URL.

How do I manage multiple environments?

Use namespaces. Create namespaces for each environment with wgc namespace create. Use the -n flag on any command to target a specific namespace.

Cosmo CLI (wgc) for Federated GraphQL Management

The problem

GraphQL deployments need automation

Manual deployments, no pre-merge validation, and ad-hoc environment management produce inconsistent results and let breaking changes reach production.

Manual schema deployments introduce errors

Deploying subgraph schemas through the Studio UI is slow and error-prone. There is no consistent process, no pre-deployment validation, and no audit of who deployed what.

Breaking changes reach production undetected

Without a CLI-integrated check step in CI/CD, schema changes go out without validation. Teams discover breaking changes when consumers report errors.

Multi-environment management lacks consistency

Managing separate dev, staging, and production environments with different scripts and web UI actions produces inconsistent results and makes promotion error-prone.

Our solution

Full lifecycle management from one CLI

wgc handles the full lifecycle of your federated graph. Install once, authenticate with an API key, and use the same commands across every environment.

From install to production

Install wgc with npm install -g wgc@latest or run it without installation via npx -y wgc@latest.
Set the COSMO_API_KEY environment variable to authenticate with the Cosmo control plane.
Run wgc subgraph check to validate schema changes. The check validates composition with all connected federated graphs and analyzes breaking changes against client traffic patterns.
On merge, run wgc subgraph publish to deploy the schema. The federated graph recomposes automatically.
Use the -n flag to target specific namespaces. Manage dev, staging, and production with identical commands.
From v0.63.0, set HTTPS_PROXY or HTTP_PROXY to use the CLI behind a corporate proxy.

One CLI. Every environment. Every stage of the lifecycle.

Cosmo CLI (wgc)

Before & After

Before Cosmo	With Cosmo
Manual deployments via the Studio UI	wgc subgraph publish automates schema deployment
No pre-deployment schema validation	wgc subgraph check catches breaking changes before merge
Separate tools for each environment	-n flag targets any namespace consistently
No CI/CD integration for GraphQL management	COSMO_API_KEY env var enables automated pipeline auth

Configuration

Key environment variables

COSMO_API_KEY: API key for authenticating with the Cosmo control plane.
COSMO_API_URL: URL of the control plane. Defaults to Cosmo Cloud. Set for self-hosted deployments.
HTTPS_PROXY / HTTP_PROXY: Company proxy URL. Supported from wgc v0.63.0.
VCS env vars: Commit, branch, and author context for traceability in check results.

How the Cosmo CLI works

01

npm or npx. Node.js LTS required.

Install

Run npm install -g wgc@latest. Node.js LTS is required. Alternatively, run commands without installation using npx -y wgc@latest.

02

COSMO_API_KEY for auth.

Authenticate

Set COSMO_API_KEY as an environment variable. For self-hosted control planes, also set COSMO_API_URL.

03

Composition + breaking change check.

Check

Run wgc subgraph check <name> --schema schema.graphql before merging. Validates composition and analyzes breaking changes against real client traffic.

04

Automated schema deployment.

Publish

Run wgc subgraph publish <name> --schema schema.graphql to deploy. The federated graph recomposes automatically with the new schema.

Capabilities

What wgc gives you

Full lifecycle management

Create, check, publish, and delete subgraphs, federated graphs, monographs, namespaces, and routers. All from a single CLI.

Pre-deployment schema check

wgc subgraph check validates composition and analyzes breaking changes against client traffic patterns before any schema reaches production.

Namespace management

Use -n to target any namespace. Manage dev, staging, and production with the same set of commands.

CI/CD native

Authenticate via COSMO_API_KEY. Proxy support from v0.63.0. Designed to run in automated pipelines.

Automate your GraphQL deployments

Install wgc, add a check step to CI, and ship schema changes with confidence.

Start Free Read the Docs

Manage your entire federated graph from the command line