# WunderGraph Cosmo CLI (`wgc`)

**The all-in-one CLI for managing federated GraphQL APIs with [WunderGraph Cosmo](https://cosmo-docs.wundergraph.com/).**

![npm](https://img.shields.io/npm/v/wgc) ![License](https://img.shields.io/npm/l/wgc) ![Downloads](https://img.shields.io/npm/dw/wgc)

---

## 🚀 What is `wgc`?

`wgc` is the official CLI for [WunderGraph Cosmo](https://cosmo-docs.wundergraph.com/), 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](https://nodejs.org/) v22+ (>=22.11.0)

### Install via npm

```bash
npm install -g wgc@latest
```

Or use `npx`:

```bash
npx -y wgc@latest
```

---

## 🛠️ Getting Started

### 1. Clone the Example Project

Start with the [Cosmo Demo](https://github.com/wundergraph/cosmo-demo), which includes two subgraphs (`posts` and `users`) and a router configuration.

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

### 2. Install `wgc`

Ensure you have `wgc` installed globally:

```bash
npm install -g wgc@latest
```

### 3. Start Subgraphs

Make the startup script executable and run it:

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

Verify the subgraphs are running:

- [Posts Subgraph](http://localhost:4001/graphql)
- [Users Subgraph](http://localhost:4002/graphql)

### 4. Generate Router Configuration

Navigate to the `router` directory and compose the router configuration:

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

### 5. Run the Router

Start the router using Docker:

```bash
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](http://localhost:3002).

Example query:

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

---

## 📚 Documentation

- **CLI Reference**: [https://cosmo-docs.wundergraph.com/cli](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](https://cosmo-docs.wundergraph.com/tutorial/from-zero-to-federation-in-5-steps-using-cosmo)
- **Full Documentation**: [https://cosmo-docs.wundergraph.com/](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**:

```bash
npx wgc namespace create production
```

- **Create Federated Graph**:

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

- **Create Subgraph**:

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

- **Check Subgraph Schema Changes**:

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

- **Generate Router Configuration locally**:

Composition Configuration (graph.yaml):

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

Generate CMD:

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

- **Run Router**:

```bash
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](https://github.com/wundergraph/cosmo-demo)
- **Cosmo GitHub Repository**: [https://github.com/wundergraph/cosmo](https://github.com/wundergraph/cosmo)
- **WunderGraph Website**: [https://wundergraph.com](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**](https://wundergraph.com/blog/scaling-graphql-federation-for-the-superbowl)
- [**The Architecture of our Observability Stack**](https://wundergraph.com/blog/scaling_graphql_observability)
- [**How Normalization affects Query Planning**](https://wundergraph.com/blog/normalization_query_planning_graphql_federation)
- [**Zero cost abstraction for the @skip and @include Directives**](https://wundergraph.com/blog/zero_cost_abstraction_for_skip_include_in_federated_graphql)
- [**Algorithm to minify GraphQL ASTs by up to 99%**](https://wundergraph.com/blog/graphql_query_ast_minification)
- [**Federated GraphQL Subscriptions with NATS and Event Driven Architecture**](https://wundergraph.com/blog/distributed_graphql_subscriptions_with_nats_and_event_driven_architecture)
- [**Implementing the viewer pattern in GraphQL Federation**](https://wundergraph.com/blog/graphql_federation_viewer_pattern)
- [**How we're using Epoll/Kqueue to scale GraphQL Subscriptions**](https://wundergraph.com/blog/edfs_scaling_graphql_subscriptions_in_go)
- [**ASTJSON - A fast way to merge JSON objects**](https://wundergraph.com/blog/astjson_high_performance_json_transformations_in_golang)
- [**Dataloader 3.0, an efficient algorithm for Federation data loading**](https://wundergraph.com/blog/dataloader_3_0_breadth_first_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:

```shell
export COSMO_TELEMETRY_DISABLED=true
```

or

```shell
export DO_NOT_TRACK=1
```

---

## 📄 License

This project is licensed under the [Apache 2.0 License](https://github.com/wundergraph/cosmo/blob/main/LICENSE).

---

## 📬 Support & Community

- **Discord**: Join our [Discord community](https://wundergraph.com/discord) for support and discussions
- **GitHub Issues**: Report issues or request features on our [GitHub repository](https://github.com/wundergraph/cosmo/issues)

---

Empower your GraphQL Federation development with `wgc` and WunderGraph Cosmo!