Install

The npm package is graph-spec-cli. The command it installs is graphspec. The two names differ because npm rejects graphspec as too similar to an unrelated existing package.

That distinction matters in exactly one place: npx resolves package names, so the portable invocation is npx graph-spec-cli.

Run without installing

npx graph-spec-cli validate spec/

This is the form used throughout these docs and by both agent skills, because it works in any directory with no prior setup.

Install the command

npm install -g graph-spec-cli
graphspec validate spec/

A global install puts graphspec on your PATH, which is the shorter thing to type if you run it often.

Per project instead of globally:

npm install --save-dev graph-spec-cli
npx graphspec validate spec/

Once the package is a local dependency, npx graphspec resolves from node_modules/.bin, so either name works.

Requirements

Node.js 20 or newer. The package is ESM only: import it, do not require it.

Install the agent skills

The two skills install with the skills CLI, which supports Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini, and others:

npx skills add brandonburrus/graphspec

Command	Effect
npx skills add brandonburrus/graphspec	Choose skills and agents interactively
npx skills add brandonburrus/graphspec -s create-graph-spec	Install one skill
npx skills add brandonburrus/graphspec --all	Every skill, every agent, no prompts
npx skills add brandonburrus/graphspec -g	Install at user level instead of project level

Note that the skills argument is the GitHub repository (brandonburrus/graphspec), which is a different string from the npm package name. See Agent skills.

Use as a library

npm install graph-spec-cli

import { loadBundle, Graph, validateBundle } from "graph-spec-cli";

The full surface is in the JavaScript API reference.

Verify

npx graph-spec-cli --version
npx graph-spec-cli --help