Get started with the npm kit

The npm packages are the client for ClearRun. Install @clearrun/sdk, @clearrun/cli, or @clearrun/mcp. Node.js 18 or newer is required. Mock mode on the SDK returns local test scores and never signs them. Real scores come from the hosted API.

Last updated November 9, 2026

Install

npm install @clearrun/sdk
npm install -g @clearrun/cli

@clearrun/sdk depends on @clearrun/core-types. The packages are MIT licensed. The hosted scoring service is licensed separately. Source: github.com/Adepoco/ClearRun.

Try it with no account

Pass { forceMock: true } for local development only. The mock returns a schema-valid verdict. It is not a hosted score, and it is not signed. The CLI and the MCP server do not offer this mock.

import { createKernelClient } from '@clearrun/sdk';

const client = createKernelClient({ forceMock: true });
const { verdict } = await client.score({
  responseText: 'The Eiffel Tower is definitely in Berlin.',
});
console.log(verdict.score, verdict.grade, verdict.summary);

If you do not pass forceMock and no API key is configured, the SDK throws MissingApiKeyError. It does not silently fall back to a mock score.

Switch to real scores

Create a key (see How to store and revoke API keys), then drop forceMock:

import { createKernelClient } from '@clearrun/sdk';

const client = createKernelClient({
  hosted: { apiKey: process.env.CLEARRUN_API_KEY },
});

const scored = await client.score({
  responseText: 'The capital of France is Paris.',
});

console.log(scored.verdict.score, scored.verdict.grade, scored.verdict.verdictId);

createKernelClient() with no arguments reads CLEARRUN_API_KEY, then the key saved by clearrun login.