Get started fast.

VerisKit needs Node.js 20 or newer, a git repository, and npm / npx. There is no account, no API key, and no install script.

Run init from the repo root. It detects your stack and writes .veris/config.json. Detection is read-only and never overwrites an existing config.

npx veriskit init

The package is veriskit; the command it installs is veris. To keep veris on your PATH, add it as a dev dependency:

npm install -D veriskit

Then every command runs as veris <command>.

From an initialized repo, prove a change and write the report in two commands.

veris verify
veris report

verify runs every configured check in parallel and prints the verdict. report writes a Markdown summary to .veris/reports/ that you paste straight into the pull request. A clean run reads like this:

VerisKit

Project     veriskit

Checks
  ✓ types          1.2s
  ✓ unit           2.4s
  ✓ lint           0.6s

Result
  ✓ Verified

Commit      4fa33a9 · tree clean

Report
  .veris/reports/verify-20260710-153000.md

veris doctor checks your environment and detected stack if a command behaves unexpectedly, and veris test runs the detected test tool on its own.

VerisKit returns one verdict with three states, not two. A wall of green checkmarks does not tell you whether a change is safe, so VerisKit reads the real exit codes and output of each check and never folds a skipped or unknown result into verified.

Verdict	Exit code	Meaning
verified	0	every configured check ran and passed
failed	1	at least one check failed
partial	2 (0 with --partial-ok)	no failures, but a check was skipped or its result is unknown

A partial verdict is not a pass. It means a check could not run or its result is unknown, for example a tool that is configured but missing, or a suite that reported nothing. Use --partial-ok when you want to accept a partial on purpose; it exits 0 while still labeling the run partial in the output and the report. The exit codes are stable, so a pull request or CI job can gate on them directly.

Running the whole suite on every save is slow enough that people skip it. VerisKit narrows the run to what your change actually reached.

veris affected
veris affected --base main
veris watch

affected runs only the checks, and only the test files, reached by your changes, using an import graph built from the project's own TypeScript. Pass --base <ref> to scope it to a PR or CI diff. watch re-runs the affected checks as files change, with native fs.watch and a --poll fallback.

Narrowing is conservative. When VerisKit cannot prove a smaller set is safe, it runs the full suite, so an affected test is never skipped. affected and watch never report a bare Verified either: a scoped run says so, so you always know whether the verdict covered everything or only the slice you touched.

Coverage percentages hide the risk. VerisKit maps how the code connects, then points at the files that matter and have no tests behind them.

veris scan
veris plan

scan maps the import graph from the project's own TypeScript, with a dependency-free scanner fallback, writes .veris/graph.json, and surfaces untested high-impact files. plan turns that into prioritized recommendations: high-impact untested files, weak verification, and risky changes.

Both are read-only and analysis only. VerisKit recommends what to test; it does not generate tests or edit your code.

Every verify and affected run writes a canonical, git-anchored record, so a verdict is something you can recompute later rather than a line in a log.

veris evidence show
veris evidence bundle
veris evidence verify .veris/evidence/<bundle>.json

Each run writes .veris/runs/<id>/evidence.json (schema veriskit/evidence@1) with a sha256 integrity digest over the whole record and a sha256 of each per-check log. evidence show prints the latest record's key facts. evidence bundle packages the latest run, the record, report, and logs, each digested, into one portable proof file under .veris/evidence/. evidence verify <file> recomputes the digests and checks a record or a bundle.

An integrity digest detects later edits and corruption. On its own it is not forgery-proof, so publish the digest separately or sign it, as below.

Since 0.4.1 you can sign a record, so a reviewer can check that it came from a key you control and nothing changed after.

veris evidence keygen
veris evidence sign .veris/runs/<id>/evidence.json
veris evidence verify .veris/runs/<id>/evidence.json --pubkey keys/veris.pub

evidence keygen creates an Ed25519 keypair using Node's built-in crypto, so signing adds no dependency. veris init gitignores keys/. evidence sign <evidence.json> writes a detached signature over the record's integrity digest, and a bundle carries the signature with it.

evidence verify finds a sibling signature and checks it on its own. Pass --pubkey <file> or --key-id <id> to assert who the signer must be. In CI, set VERISKIT_SIGNING_KEY to supply the key.

Signing is opt-in, and unsigned evidence still verifies for integrity.

A signature proves that a key vouched for this record. It does not prove who holds that key, unless you assert the expected signer with --pubkey or --key-id. Keyless signing through sigstore is still planned.

Your verdict lands in your terminal. The reviewer is in the pull request. Pass --github and VerisKit posts it there.

veris verify --github

That posts and updates one sticky PR comment carrying the verdict and report, and creates a GitHub Check Run whose conclusion follows the verdict: verified passes, failed fails, and partial is neutral. Re-runs edit the same comment rather than adding another, so a busy PR does not fill up with bot noise.

VerisKit reads GITHUB_TOKEN from the environment and never stores it. In a workflow, grant the job both permissions:

permissions:
  pull-requests: write
  checks: write

Without them the publish fails with GitHub's own message, for example "Resource not accessible by integration". Since 0.5.1 VerisKit surfaces that message so a failed publish is diagnosable, and the token never appears in an error.

Publishing is a side channel, and it cannot rescue a bad run. A missing token or a run outside a PR prints a notice and the exit code still reflects the verdict. A GitHub API error is reported and then ignored. The verdict comes from your checks, never from whether the comment posted.

veris badge writes a shields.io endpoint JSON so a README badge shows the last verdict. All of this uses the GitHub API over Node's built-in fetch, so none of it adds a dependency.

VerisKit can run your Playwright suite as part of the verdict. It is opt-in, so a normal veris verify stays fast.

veris verify --browser

That runs playwright test alongside your other checks and folds the result into the same honest verdict. To make it part of every run instead, add a browser entry to .veris/config.json.

When init detects Playwright, veris doctor lists browser as an available capability, so you can see it is there before you turn it on.

If VerisKit cannot parse the results, it reports the check as unknown rather than claiming it passed. That turns the run partial, which is the honest answer: the browser suite ran, and VerisKit cannot tell you what it proved.

Every run leaves an evidence record, so VerisKit can show you the trend instead of just the last result.

veris log
veris log --flaky

veris log lists past runs newest first, each with its verdict, its checks, and the commit it ran against. veris log --flaky reads across recent runs and names the checks that both passed and failed. Those are the ones to fix before you trust a green run.

History is local to the machine. The .veris/runs directory is gitignored, so a teammate's runs are not in your log, and your log does not land in the repo.

Since 0.6.0, VerisKit ships veriskit-mcp, a Model Context Protocol server over stdio, so an AI agent verifies its own change against your real tooling and reads the evidence back as tool calls, rather than reporting that the work is done.

Point any MCP-aware client at the package:

{
  "mcpServers": {
    "veriskit": { "command": "npx", "args": ["-y", "veriskit-mcp"] }
  }
}

The server exposes seven tools. Five only read:

• veris_doctor reports the environment and the detected stack.
• veris_scan maps the import graph and untested high-impact files.
• veris_plan returns the prioritized recommendations.
• veris_log returns past runs and flaky checks.
• veris_evidence_verify recomputes and checks a record or bundle.

Two run your project's test tooling:

• veris_verify runs every configured check and returns the verdict.
• veris_affected runs only the checks and test files your changes reached.

Each one returns the same structured, honest verdict the CLI returns, so a partial reads as a partial to the agent too. An agent cannot talk VerisKit into a pass, because the verdict still comes from your tools' real exit codes.

The veriskit CLI keeps its two runtime dependencies. The official MCP SDK lives only in veriskit-mcp, so the package you install in CI never grows to support an agent.

Alongside AgentLoopKit, which decides what the agent does next, and AgentFlight, which records what it did, VerisKit answers whether you can trust the result. Now the agent can ask directly.

VerisKit names its edges instead of hiding them. Today it does not:

• Detect framework routes or endpoints. It verifies the checks your project runs, not live HTTP surfaces.
• Generate tests. scan and plan recommend what to test; writing the tests is yours.
• Model monorepos. It works from one project root. Multiple packages under one repo are not modeled yet.
• Fully analyze every project. On plain-JS projects, or TypeScript 7.x native-compiler projects, it uses a dependency-free scanner fallback instead of the full graph.
• Sign without a key. evidence sign covers Ed25519 signing with your own key. Keyless signing through sigstore is still planned, and a signature proves a key vouched for the record, not who holds the key, unless you assert the signer.
• Share history across a team. veris log reads the local .veris/runs directory, which is gitignored, so history is per machine.

The CLI runs locally with two dependencies, cac and picocolors, and Node built-ins. --github is the one outbound path, and you opt into it.

The full surface, compact.

• init detects the stack and writes .veris/config.json. Read-only detection; never overwrites an existing config.
• doctor checks your environment and the detected stack, including whether browser is available.
• test runs the detected test tool on its own.
• verify runs every configured check in parallel and returns verified, failed, or partial, with exit codes 0, 1, and 2. --github posts the verdict to the PR, --browser also runs the Playwright suite, and --partial-ok exits 0 on a partial.
• report writes a Markdown summary of the latest run under .veris/reports/.
• badge writes a shields.io endpoint JSON for a README status badge.
• affected runs only the checks and test files reached by your changes. --base <ref> scopes it to a diff.
• watch re-runs affected checks as files change. --poll for filesystems that need it.
• log lists past runs from the stored evidence records. --flaky names checks that both passed and failed recently.
• scan maps the import graph and finds untested high-impact files.
• plan recommends what to test from the scan.
• evidence verify | bundle | show recomputes a record, packages a portable proof file, or prints the latest record. verify takes --pubkey or --key-id to assert the signer.
• evidence keygen | sign creates an Ed25519 keypair, or writes a detached signature over a record's digest.

Separately, the veriskit-mcp package serves seven of these to an AI agent over MCP: veris_doctor, veris_scan, veris_plan, veris_log, veris_evidence_verify, veris_verify, and veris_affected.

Everything is local and read-mostly. VerisKit runs your configured checks only when you invoke verify, affected, watch, or test, and it reaches the network only when you pass --github.