# graphql-inspector: the same diff logic in a CLI, an action and a library > GraphQL Inspector compares two GraphQL schemas and classifies every difference as breaking, non-breaking or dangerous, and it ships that one capability four ways: a GitHub App, a GitHub Action, a CLI and a programmatic API. **graphql-hive/graphql-inspector** — 🕵️‍♀️ Validate schema, get schema change notifications, validate operations, find breaking changes, look for similar types, schema coverage - Repository: https://github.com/graphql-hive/graphql-inspector - Website: https://the-guild.dev/graphql/inspector - Stars: 1,767 · Forks: 218 - Language: TypeScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/graphql-hive-graphql-inspector ## Three verdicts, and why dangerous is not a synonym for safe The core of the tool is a diff. Given two GraphQL schemas, it produces a list of changes, and the README is specific that every change is precisely explained and marked as breaking, non-breaking or dangerous. That third category is the interesting one. Binary pass or fail is the usual model for schema compatibility checks, and it forces a judgement call on anything ambiguous. A change that is not strictly breaking but has real consequences, removing a deprecated field, changing a default, altering a directive argument, gets flattened into either pass or fail. Splitting it out lets a reviewer see the difference between something that will error immediately and something that will work but change behaviour. Around that core sit four related jobs. It validates documents and fragments against a schema. It finds similar or duplicated types, which is what you want when a schema has accumulated `User` and `UserV2` and `AccountUser`. And it computes schema coverage based on operations and fragments, meaning which parts of the schema anything actually touches. The feature list also mentions serving a GraphQL server with faked data and GraphiQL, which turns out to be a development convenience rather than a separate product. ## One library, four delivery mechanisms The README lists the ways to use it, and the list is really a statement about where a schema check belongs in an organisation. The GitHub Application is the no-effort option: it posts comments on pull requests that change your schema and tells you what broke. The GitHub Action is the CI option for teams that already run their own checks. The CLI is for local use and for scripts. The programmatic API is for everything else, including building your own tooling on the same diff. That last option is what makes the project more than a checker. Because the same code is available as a library, a team can run the diff against its own registry of past schemas and enforce policy over time rather than only at merge time. The feature list also references using serverless functions to validate changes, which is that idea taken one step further. The repository supports all four from one monorepo. The root `package.json` is named `graphql-inspector-mono-repository` and is marked `private`, with `pnpm-workspace.yaml` and a `packages/` directory holding the individual packages, plus a separate `action/` directory for the GitHub Action, built from `packages/action/src/action.ts` with `ncc build` and bundled into a committed output that `prerelease` rebuilds before publishing. ## The monorepo, and the tooling behind it This is a large workspace by any measure, and the dependency list at the root hints at what it does rather than what the packages need. `probot` at version 13.2.2 is the GitHub App framework, which is what makes the hosted App possible. `yargs` is the CLI argument parser. `js-yaml` reads rule files. `immer` handles immutable state, which matters for a diff that accumulates changes. `@whatwg-node/fetch` gives a fetch implementation that works in serverless environments where there is no global one. `@sentry/node` and `@sentry/tracing` are error reporting. `shelljs` is used for scripts. Release management uses changesets: `.changeset/` at the root, `@changesets/cli` and `@changesets/changelog-github` as dev dependencies, and a `release` script of `pnpm build && pnpm changeset publish` with a `release:canary` variant. Versions are enforced. `engines` requires `node: ">=18.0.0"` and `pnpm: ">=11.27.1"`, with `packageManager` set to `pnpm@11.27.1`. That is a recent pnpm major for a package whose stable line goes back years, so a team on an older pnpm will need to upgrade before anything installs. Build and test tooling: `bob build` for building packages, `vite` for bundling, `vitest` for tests, ESLint and Prettier for style with Prettier config carried in `prettier.config.cjs`, and Renovate with `renovate.json` for dependency updates. `postinstall` runs `husky install`. Licence is MIT, and the author field credits Kamil Kisiela. ## Docker, and how the CLI gets onto your PATH The `Dockerfile` is a two-stage build and it is short enough to be worth reading in full because it explains the image layout. The build stage runs on `node:24-alpine` with `NODE_ENV=development` and `DISTDIR` set to `/usr/local/share/graphql-inspector`. It copies the repository, installs the package manager by reading `packageManager` out of the root `package.json` at build time, runs `pnpm install` and then `pnpm build`. The distribution stage is also `node:24-alpine` with `NODE_ENV=production`. It copies only `packages`, `package.json` and `pnpm-workspace.yaml` out of the build stage into `DISTDIR`, installs production dependencies only, and runs `pnpm store prune` to drop the store. The final line is the one that matters operationally. It symlinks `${DISTDIR}/packages/cli/dist/cjs/index.js` to `/usr/local/bin/graphql-inspector` and makes it executable, so the command in the image is the CommonJS build of the CLI package. Two things follow. The image runs Node 24 while the declared engine floor is Node 18, so anything that works in the image may not work on an older host. And because only `packages` is copied, the image is a runtime image for the CLI rather than a development image; the GitHub App and the action are not served from it. ## Where it sits relative to a schema registry and to codegen The README points at GraphQL Hive as a related project and describes it as an open-source performance monitoring tool and schema registry for GraphQL, available as a hosted service and offering self-hosting. The repository is under the `graphql-hive` organisation. That relationship is worth understanding because the two overlap on one axis and not the other. A registry stores schema history. GraphQL Inspector diffs two points in that history and tells you what changed and how much it matters. The `example/` directory makes the intended workflow visible: it contains `coverage.json`, a `documents/` folder, a `rules/` folder and a `schemas/` folder, which is the shape of a coverage report produced by comparing a schema against a set of real operations, and a rule file configuring how changes are judged. Against codegen tools, the distinction is that codegen types follow your schema while Inspector questions whether changing it was safe. They are complements. Most teams need both, and running Inspector in CI before codegen is the ordering that saves you a broken client build. Part of the library was ported to Node.js from Ruby's GraphQL Schema Comparator, which the README credits and links. ## Conclusion Adopt GraphQL Inspector if you publish a GraphQL schema that other teams build against, because classifying a change as breaking before you merge it is the entire problem it solves. Do not adopt it for runtime schema validation of documents in production, which is a different concern it only partly covers through operation and fragment checks. Verify first which Node version your build uses, since the root package declares `node: ">=18.0.0"` while the Docker image is built on `node:24-alpine`. ## FAQ ### How does GraphQL Inspector classify schema changes? It outputs a list of changes between two schemas, and each change is explained and marked as breaking, non-breaking or dangerous. It can also validate documents and fragments against a schema, find similar or duplicated types, and compute schema coverage from operations and fragments. ### How do I use GraphQL Inspector in a repository? The README lists four options: a GitHub Application that comments on pull requests, a GitHub Action from the marketplace for CI, a CLI, and a programmatic API. The installation and usage details are documented on the project website. ### What does GraphQL Inspector need to run? The root package declares `engines` requiring `node: ">=18.0.0"` and `pnpm: ">=11.27.1"`, with `packageManager` set to `pnpm@11.27.1`. The Docker image is built on `node:24-alpine`. ### Is GraphQL Inspector a schema registry? No. The README points to GraphQL Hive as a separate schema registry and performance monitoring tool. Inspector compares schemas and reports on documents, rather than storing schema history. ### What licence is GraphQL Inspector under? MIT, credited in the README to Kamil Kisiela. Part of the library was ported to Node.js from Ruby's GraphQL Schema Comparator. ## Sources - [graphql-hive/graphql-inspector on GitHub](https://github.com/graphql-hive/graphql-inspector) - [License: MIT](https://github.com/graphql-hive/graphql-inspector/blob/master/LICENSE) - [Project website](https://the-guild.dev/graphql/inspector) - [README](https://github.com/graphql-hive/graphql-inspector/blob/master/README.md) - [Releases](https://github.com/graphql-hive/graphql-inspector/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/graphql-hive-graphql-inspector