{"id":18012,"library":"wgc","title":"WunderGraph Cosmo CLI","description":"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.","status":"active","version":"0.114.2","language":"javascript","source_language":"en","source_url":"https://github.com/wundergraph/cosmo","tags":["javascript","wundergraph","cosmo","cli","federation","graphql","typescript"],"install":[{"cmd":"npm install wgc","lang":"bash","label":"npm"},{"cmd":"yarn add wgc","lang":"bash","label":"yarn"},{"cmd":"pnpm add wgc","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Recommended for system-wide access to wgc commands in your terminal.","wrong":"npm install wgc","symbol":"wgc (global install)","correct":"npm install -g wgc@latest"},{"note":"Useful for quick, one-off commands or CI/CD pipelines where global installation is not desired. The `-y` flag bypasses confirmation prompts.","wrong":"node wgc","symbol":"wgc (npx execution)","correct":"npx -y wgc@latest <command>"},{"note":"All wgc commands follow the pattern `wgc <command> [subcommand] [flags]`. Specific commands and their arguments can be found in the official documentation.","wrong":"wgc:router:compose","symbol":"wgc (command invocation)","correct":"wgc router compose --input graph.localhost.yaml --out config.json"}],"quickstart":{"code":"git clone https://github.com/wundergraph/cosmo-demo.git\ncd cosmo-demo\nnpm install -g wgc@latest\nchmod +x start-subgraphs.sh\n./start-subgraphs.sh &\n\ncd router\nwgc router compose --input graph.localhost.yaml --out config.json\n\ndocker run \\\n  --name cosmo-router \\\n  --rm \\\n  -p 3002:3002 \\\n  --add-host=host.docker.internal:host-gateway \\\n  --platform=linux/amd64 \\\n  -e pull=always \\\n  -e DEV_MODE=true \\\n  -e LISTEN_ADDR=0.0.0.0:3002 \\\n  -e EXECUTION_CONFIG_FILE_PATH=\"/config/config.json\" \\\n  -v \"$(pwd)/config.json:/config/config.json\" \\\n  ghcr.io/wundergraph/cosmo/router:latest\n\n# Access the federated GraphQL API at http://localhost:3002","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.114.2"},{"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>`.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install `wgc` globally using `npm install -g wgc@latest` or run commands via `npx -y wgc@latest <command>`.","cause":"The `wgc` CLI is not installed globally or is not in your system's PATH.","error":"command not found: wgc"},{"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`).","cause":"You are attempting to run `wgc` with an unsupported or outdated Node.js version.","error":"Error: Node.js v18.17.0 is not supported. Please use Node.js v20 LTS or higher."},{"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.","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.","error":"Error: ENOENT: no such file or directory, open 'graph.localhost.yaml'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}