WunderGraph Cosmo CLI (wgc)

The all-in-one CLI for managing federated GraphQL APIs with WunderGraph Cosmo.

🚀 What is wgc?

wgc is the official CLI for WunderGraph Cosmo, an open-source, full-lifecycle GraphQL API management platform.

With wgc, you can:

• Create and manage federated GraphQL APIs and subgraphs
• Perform schema checks and composition validations
• Generate and deploy router configurations
• Integrate with CI/CD pipelines for automated workflows
• Manage namespaces, API keys, and more

Whether you're building monolithic or federated GraphQL architectures, wgc provides the tools to manage your development and deployment processes.

🧰 Cosmo Features

• Federation Support: Compatible with GraphQL Federation v1 and v2
• Schema Registry: Centralized management of your GraphQL schemas with versioning and change tracking
• Composition Checks: Automated validation to ensure subgraphs compose correctly without breaking changes
• Router Configuration: Generate and manage router configurations for efficient query planning and execution
• Observability: Integrated with OpenTelemetry and Prometheus for metrics, tracing, and monitoring
• Access Control: Fine-grained access controls with support for OIDC, RBAC, and SCIM

📦 Installation

Prerequisites

• Node.js v20 LTS or higher

Install via npm

npm install -g wgc@latest

Or use npx:

npx -y wgc@latest

🛠️ Getting Started

1. Clone the Example Project

Start with the Cosmo Demo, which includes two subgraphs (posts and users) and a router configuration.

git clone https://github.com/wundergraph/cosmo-demo.git
cd cosmo-demo

2. Install wgc

Ensure you have wgc installed globally:

npm install -g wgc@latest

3. Start Subgraphs

Make the startup script executable and run it:

chmod +x start-subgraphs.sh
./start-subgraphs.sh

Verify the subgraphs are running:

• Posts Subgraph
• Users Subgraph

4. Generate Router Configuration

Navigate to the router directory and compose the router configuration:

cd router
wgc router compose --input graph.localhost.yaml --out config.json

5. Run the Router

Start the router using Docker:

docker run \
  --name cosmo-router \
  --rm \
  -p 3002:3002 \
  --add-host=host.docker.internal:host-gateway \
  --platform=linux/amd64 \
  -e pull=always \
  -e DEV_MODE=true \
  -e LISTEN_ADDR=0.0.0.0:3002 \
  -e EXECUTION_CONFIG_FILE_PATH="/config/config.json" \
  -v "$(pwd)/config.json:/config/config.json" \
  ghcr.io/wundergraph/cosmo/router:latest

6. Query the Federated Graph

Access the federated GraphQL API at http://localhost:3002.

Example query:

query {
  posts {
    id
    content
    author {
      id
      name
    }
  }
}

📚 Documentation

• CLI Reference: https://cosmo-docs.wundergraph.com/cli
• Zero to Federation Tutorial: https://cosmo-docs.wundergraph.com/tutorial/from-zero-to-federation-in-5-steps-using-cosmo
• Full Documentation: https://cosmo-docs.wundergraph.com/

🌐 About WunderGraph Cosmo

WunderGraph Cosmo is a comprehensive, open-source platform for managing GraphQL APIs at scale. It offers:

• Schema Registry: Centralized schema management with versioning and validation
• Cosmo Studio: A web interface for exploring schemas, monitoring performance, and managing access
• Cosmo Router: A high-performance, Go-based router supporting federation, subscriptions, and more
• Observability: Built-in support for OpenTelemetry and Prometheus
• Security: Fine-grained access controls with OIDC, RBAC, and SCIM support

Cosmo can be deployed on-premises, in the cloud, or used as a managed service.

🧪 Example Commands

• Create Namespace:

npx wgc namespace create production

• Create Federated Graph:

npx wgc federated-graph create main -r http://router.example.com/graphql -n production

• Create Subgraph:

npx wgc subgraph create products --routing-url http://localhost:4001/graphql

• Check Subgraph Schema Changes:

npx wgc subgraph check products -n production --schema ./schemas/products.graphql

• Generate Router Configuration locally:

Composition Configuration (graph.yaml):

version: 1
subgraphs:
  - name: products
    routing_url: http://localhost:4001/graphql
    schema:
      file: ./schemas/products.graphql

Generate CMD:

npx wgc router compose -i graph.yaml -o config.json

• Run Router:

docker run \
  --name cosmo-router \
  --rm \
  -p 3002:3002 \
  --add-host=host.docker.internal:host-gateway \
  --platform=linux/amd64 \
  -e pull=always \
  -e DEV_MODE=true \
  -e LISTEN_ADDR=0.0.0.0:3002 \
  -e EXECUTION_CONFIG_FILE_PATH="/config/config.json" \
  -v "$(pwd)/config.json:/config/config.json" \
  ghcr.io/wundergraph/cosmo/router:latest

🔗 Related Projects

• Cosmo Demo: https://github.com/wundergraph/cosmo-demo
• Cosmo GitHub Repository: https://github.com/wundergraph/cosmo
• WunderGraph Website: https://wundergraph.com

🔗 From the WunderGraph Blog

Here's a selection of blog posts that focus on the technical aspects of Cosmo:

• How we scaled Cosmo Router for the SuperBowl
• The Architecture of our Observability Stack
• How Normalization affects Query Planning
• Zero cost abstraction for the @skip and @include Directives
• Algorithm to minify GraphQL ASTs by up to 99%
• Federated GraphQL Subscriptions with NATS and Event Driven Architecture
• Implementing the viewer pattern in GraphQL Federation
• How we're using Epoll/Kqueue to scale GraphQL Subscriptions
• ASTJSON - A fast way to merge JSON objects
• Dataloader 3.0, an efficient algorithm for Federation data loading

Telemetry

The CLI tool collects usage data to help us improve the tool and understand how users interact with it. You can disable telemetry in one of the following ways:

export COSMO_TELEMETRY_DISABLED=true

or

export DO_NOT_TRACK=1

📄 License

This project is licensed under the Apache 2.0 License.

📬 Support & Community

• Discord: Join our Discord community for support and discussions
• GitHub Issues: Report issues or request features on our GitHub repository

Empower your GraphQL Federation development with wgc and WunderGraph Cosmo!