WunderGraph Cosmo CLI

0.114.2 verified Thu Apr 23 auth: no javascript

The `wgc` package is the official command-line interface (CLI) for WunderGraph Cosmo, an open-source, full-lifecycle GraphQL API management platform. It empowers developers to manage federated GraphQL APIs and subgraphs, perform critical schema checks and composition validations, generate and deploy router configurations, and integrate these processes seamlessly into CI/CD pipelines. As of its current stable version `0.114.2`, the project exhibits a highly active release cadence across its components, including the router and control plane, indicating continuous development. Key differentiators include its comprehensive support for GraphQL Federation v1 and v2, a centralized Schema Registry with versioning, automated composition checks for breaking changes, integrated observability with OpenTelemetry and Prometheus, and robust access control mechanisms like OIDC, RBAC, and SCIM.

Common errors

error command not found: wgc ↓

cause The `wgc` CLI is not installed globally or is not in your system's PATH.

fix

Install wgc globally using npm install -g wgc@latest or run commands via npx -y wgc@latest <command>.

error Error: Node.js v18.17.0 is not supported. Please use Node.js v20 LTS or higher. ↓

cause You are attempting to run `wgc` with an unsupported or outdated Node.js version.

fix

Upgrade your Node.js environment to v20 LTS or higher. Consider using nvm (Node Version Manager) to easily manage and switch Node.js versions (e.g., nvm install 20 && nvm use 20).

error Error: ENOENT: no such file or directory, open 'graph.localhost.yaml' ↓

cause The input file specified for a `wgc` command (e.g., `wgc router compose`) does not exist at the provided path, or the current working directory is incorrect.

fix

Verify the file path provided to the command. Ensure the file exists and that you are executing the command from the correct directory, or provide the full absolute path to the file.

Warnings

gotcha The `wgc` CLI tool requires Node.js v20 LTS or higher to function correctly. Using older versions may lead to installation errors or unexpected runtime behavior. ↓

fix Ensure Node.js v20 LTS or higher is installed on your system. It is recommended to use a version manager like `nvm` (e.g., `nvm install 20 && nvm use 20`) to manage Node.js versions.

gotcha The quickstart guide and common deployment patterns for the Cosmo router heavily rely on Docker. Users without Docker installed and properly configured will be unable to run the router locally as described. ↓

fix Install Docker Desktop or a compatible Docker engine for your operating system. Verify Docker is running and accessible from your terminal before attempting to run the Cosmo router.

gotcha Installing `wgc` locally using `npm install wgc` (without the `-g` flag) will not add the `wgc` command to your system's PATH. This means direct `wgc` command invocation will fail with a 'command not found' error. ↓

fix For global terminal access, use `npm install -g wgc@latest`. If a local installation is required (e.g., for project-specific scripts), use `npx wgc <command>` or reference the local executable via `$(npm bin)/wgc <command>`.

Install

npm install wgc

yarn add wgc

pnpm add wgc

Imports

wgc (global install)
wrong
```
npm install wgc
```
correct
```
npm install -g wgc@latest
```
Recommended for system-wide access to wgc commands in your terminal.
wgc (npx execution)
wrong
```
node wgc
```
correct
```
npx -y wgc@latest <command>
```
Useful for quick, one-off commands or CI/CD pipelines where global installation is not desired. The `-y` flag bypasses confirmation prompts.
wgc (command invocation)
wrong
```
wgc:router:compose
```
correct
```
wgc router compose --input graph.localhost.yaml --out config.json
```
All wgc commands follow the pattern `wgc <command> [subcommand] [flags]`. Specific commands and their arguments can be found in the official documentation.

Quickstart

Demonstrates how to set up a local federated GraphQL environment using WunderGraph Cosmo, including installing the CLI, starting example subgraphs, composing a router configuration, and running the Cosmo router via Docker.

git clone https://github.com/wundergraph/cosmo-demo.git
cd cosmo-demo
npm install -g wgc@latest
chmod +x start-subgraphs.sh
./start-subgraphs.sh &

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

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

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