1. Copy the source/packages/ directory into your project, e.g. vendor/spectral/.

2. Add path aliases in tsconfig.json so local imports resolve correctly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@stoplight/spectral-core": ["vendor/spectral/core/src/index.ts"],
      "@stoplight/spectral-formats": ["vendor/spectral/formats/src/index.ts"],
      "@stoplight/spectral-functions": ["vendor/spectral/functions/src/index.ts"],
      "@stoplight/spectral-rulesets": ["vendor/spectral/rulesets/src/index.ts"],
      "@stoplight/spectral-parsers": ["vendor/spectral/parsers/src/index.ts"],
      "@stoplight/spectral-runtime": ["vendor/spectral/runtime/src/index.ts"]
    },
    "module": "commonjs",
    "target": "ES2020",
    "strict": true
  }
}

3. If using Webpack or esbuild for the CLI, alias the same packages in your bundler config.

4. No required environment variables for programmatic use. For CLI proxy support, set PROXY=http://your-proxy:3128 before running the spectral binary.

5. To build the CLI entry point directly: ts-node vendor/spectral/cli/src/index.ts lint myapi.yaml.

Public API

Spectral

import { Spectral } from '@stoplight/spectral-core';

class Spectral {
  constructor(options?: { resolver?: IResolver });
  ruleset: Ruleset | undefined;
  run(input: string | Document): Promise<ISpectralDiagnostic[]>;
}

The main linting engine. Instantiate it, assign a Ruleset, then call run() with a raw string or a Document instance. Returns an array of diagnostics describing every rule violation found.

Document

import { Document } from '@stoplight/spectral-core';

class Document {
  constructor(
    content: string,
    parser: IParser,
    source?: string
  );
}

Wraps raw document content with a parser (YAML or JSON). Pass the result directly to Spectral.run(). Supplying source enables correct $ref resolution relative to that path.

ISpectralDiagnostic

import type { ISpectralDiagnostic } from '@stoplight/spectral-core';

interface ISpectralDiagnostic {
  code: string | number;
  message: string;
  severity: 0 | 1 | 2 | 3; // error, warn, info, hint
  path: (string | number)[];
  range: { start: { line: number; character: number }; end: { line: number; character: number } };
  source?: string;
}

Every item returned from Spectral.run(). Use severity === 0 to gate CI failure. path gives the JSON Pointer segments to the offending node.

CLIError

import { CLIError } from './errors'; // vendor/spectral/cli/src/errors/index.ts

class CLIError extends Error {}

Thrown by CLI services when unrecoverable errors occur (bad ruleset path, unreadable file). Catch this in custom CLI wrappers to emit clean user-facing messages without stack traces.

Working examples

Scenario - Lint an OpenAPI file programmatically

Load an OpenAPI 3 document from disk, apply the built-in OAS ruleset, and print all errors to stdout.

import { Spectral, Document } from '@stoplight/spectral-core';
import { Parsers } from '@stoplight/spectral-parsers';
import { bundleAndLoadRuleset } from '@stoplight/spectral-ruleset-bundler/with-loader';
import * as fs from 'fs';
import * as path from 'path';

async function lintOpenAPI(filePath: string): Promise<void> {
  const content = fs.readFileSync(filePath, 'utf8');
  const doc = new Document(content, Parsers.Yaml, filePath);

  const spectral = new Spectral();
  spectral.ruleset = await bundleAndLoadRuleset(
    path.resolve(__dirname, '.spectral.yaml'),
    { fs, fetch }
  );

  const results = await spectral.run(doc);
  const errors = results.filter(d => d.severity === 0);

  if (errors.length > 0) {
    errors.forEach(e =>
      console.error(`[${e.code}] ${e.message} at ${e.path.join('.')} (line ${e.range.start.line + 1})`)
    );
    process.exit(1);
  }

  console.log('No errors found.');
}

lintOpenAPI('./openapi.yaml').catch(console.error);

Scenario - Run with an inline custom ruleset

Define a ruleset entirely in code without a file on disk, useful for embedded governance logic.

import { Spectral, Document, Ruleset } from '@stoplight/spectral-core';
import { truthy } from '@stoplight/spectral-functions';
import { Parsers } from '@stoplight/spectral-parsers';

async function runCustomRuleset(yamlContent: string): Promise<void> {
  const doc = new Document(yamlContent, Parsers.Yaml);

  const ruleset = new Ruleset({
    rules: {
      'require-info-title': {
        given: '$.info.title',
        severity: 'error',
        then: { function: truthy },
        message: 'API must have an info.title',
      },
    },
  });

  const spectral = new Spectral();
  spectral.ruleset = ruleset;

  const diagnostics = await spectral.run(doc);
  diagnostics.forEach(d => console.log(`${d.severity === 0 ? 'ERROR' : 'WARN'}: ${d.message}`));
}

const sample = `info:\n  version: '1.0'\npaths: {}`;
runCustomRuleset(sample).catch(console.error);

Scenario - Use the CLI programmatically inside a Node.js script

Invoke the Spectral CLI command object directly from Node rather than spawning a subprocess.

import yargs from 'yargs';
import lintCommand from './vendor/spectral/cli/src/commands/lint';

const cli = yargs
  .scriptName('spectral')
  .command(lintCommand)
  .help(false)
  .version(false);

// Equivalent to: spectral lint api.yaml --ruleset .spectral.yaml --fail-severity error
cli.parse(['lint', 'api.yaml', '--ruleset', '.spectral.yaml', '--fail-severity', 'error']);

File walkthrough

• cli/ - Yargs CLI entrypoint; src/commands/lint.ts is the lint command; src/services/linter/ handles file collection, ruleset loading, and output; src/errors/ defines CLIError.
• core/ - Contains Spectral, Document, ParsedDocument, Ruleset, Rule, runner logic, type guards, and all shared TypeScript types.
• formats/ - Format detection functions (e.g. isOpenApiv3, isAsyncApi2) used in ruleset formats fields.
• formatters/ - Output formatters consumed by the CLI; each exports a function (diagnostics, options) => string.
• functions/ - Pure rule functions (truthy, pattern, schema, etc.) imported directly into ruleset then.function fields.
• parsers/ - Exports Parsers.Yaml and Parsers.Json for use with Document constructor.
• ref-resolver/ - Resolves $ref pointers within and across documents; wraps @stoplight/json-ref-resolver.
• ruleset-bundler/ - Bundles ruleset files that import JS/TS functions into self-contained objects.
• ruleset-migrator/ - CLI tool and API to migrate .spectral.yml v5 rulesets to v6 format.
• rulesets/ - Prebuilt rulesets (oas, asyncapi, arazzo) with all rules and aliases defined.
• runtime/ - Exports DEFAULT_REQUEST_OPTIONS and shared fetch helpers used by the CLI and ref-resolver.

Common pitfalls and fixes

• ESM/CJS mismatch: Several sub-packages ship dual ESM+CJS. If you see ERR_REQUIRE_ESM, set "moduleResolution": "bundler" or "node16" in tsconfig.json and use dynamic import().
• Missing fetch global in Node < 18: The ref-resolver uses fetch; polyfill with npm install node-fetch and global.fetch = require('node-fetch') before importing Spectral.
• ajv version conflict: Spectral requires ajv@^8; if another dependency pins ajv@6, hoist ajv@8 explicitly in package.json#resolutions (Yarn) or overrides (npm 8+).
• Ruleset path resolution: bundleAndLoadRuleset resolves extends relative to the ruleset file's directory, not process.cwd(); always pass an absolute path via path.resolve().
• source missing on Document: Without a source path, cross-file $ref resolution fails silently; always supply the absolute file path as the third constructor argument.
• TypeScript strict mode errors in runner: The runner uses mapped types that require "strictNullChecks": true; ensure it is not disabled in your tsconfig.

Vibe-coding prompt template

I have dropped the Stoplight Spectral monorepo source into `vendor/spectral/`
(from the upstream package `stoplightio_spectral`). I also have USAGE.md in
the same directory describing the real exports and setup steps.

Please help me integrate Spectral into my Node.js/TypeScript project step by step:

1. Read USAGE.md and vendor/spectral/ to understand the available packages and
   their exports (Spectral, Document, ISpectralDiagnostic, Ruleset, CLIError, etc.).
2. Add the required tsconfig paths so @stoplight/spectral-* imports resolve to
   vendor/spectral/<package>/src/index.ts.
3. Install any missing npm dependencies listed in USAGE.md ## Required dependencies.
4. Create a `src/lint.ts` module that: accepts a file path, parses it with
   Parsers.Yaml, loads a ruleset from `.spectral.yaml`, runs Spectral, and
   returns all ISpectralDiagnostic results.
5. Add a CI check script `scripts/ci-lint.ts` that exits with code 1 if any
   diagnostic has severity 0 (error).
6. If I have a custom rule requirement, show me how to define an inline Ruleset
   with a custom function imported from vendor/spectral/functions/.

Use only exports that exist in vendor/spectral/ and are documented in USAGE.md.
Do not invent APIs.

License and credit

Spectral is released under the Apache 2.0 License (see source/cli/LICENSE and source/core/LICENSE). Upstream repository and package: @stoplight/spectral-core by Stoplight.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Automation, Utilities & Developer Tools

Free