Thymian

0.1.8 verified Fri May 01 auth: no javascript

Thymian is an open-source HTTP conformance and API governance tool v0.1.8 (released April 2026, active development with frequent releases every 1-2 weeks). It validates APIs against RFC 9110 and OpenAPI specifications, offering static, live endpoint, and recorded traffic analysis. Key differentiators: language-agnostic, extensible via plugins (npm packages or WebSocket), educational reports explaining RFC semantics, and a unified rule system that works across lint, test, and analyze commands.

Common errors

error npx thymian --version error: unknown command '--version' ↓

cause Version flag expects a subcommand; run 'npx thymian --version' should work, but if using an older version the flag may not be supported.

fix

Update to latest version: 'npx thymian@latest --version' or use 'npx thymian version'.

error Error: Cannot find module '@thymian/cli' ↓

cause Using the deprecated scoped package name. The package is now published as 'thymian'.

fix

Use 'npx thymian' instead of 'npx @thymian/cli'.

error Error: Failed to load plugin: thymian-plugin-har ... Cannot find module 'thymian-plugin-har' ↓

cause The HAR plugin is not installed. It is an optional plugin and must be installed separately.

fix

Run 'npm install thymian-plugin-har' or 'npm install -g thymian-plugin-har'.

Warnings

breaking In v0.1.7 the flag --skip-spec-validation was replaced with --validate-specs. Old flag no longer works. ↓

fix Use --validate-specs instead of --skip-spec-validation.

deprecated The scoped package @thymian/cli was replaced by unscoped 'thymian' in v0.1.1. The scoped package is deprecated. ↓

fix Use 'npx thymian' instead of 'npx @thymian/cli'. Reinstall using 'npm uninstall -g @thymian/cli && npm install -g thymian'.

gotcha Plugin HAR loader requires explicit configuration via thymian.config.yaml; it is not enabled by default. ↓

fix Add 'plugins: ["thymian-plugin-har"]' to your thymian.config.yaml or use '--plugin thymian-plugin-har'.

gotcha When using 'thymian test' with a target URL, the target must be reachable from your network (no localhost overlay). ↓

fix Ensure the target URL is publicly accessible or on the same network; use '--target http://localhost:8080' for local testing.

Install

npm install thymian

yarn add thymian

pnpm add thymian

Imports

thymian (CLI)
wrong
```
npx @thymian/cli lint --spec openapi:openapi.yaml
```
correct
```
npx thymian lint --spec openapi:openapi.yaml
```
Package was previously scoped @thymian/cli; as of v0.1.1 it is published as unscoped 'thymian'. Use 'npx thymian' directly.
ThymianConfig
wrong
```
import { ThymianConfig } from '@thymian/cli'
```
correct
```
import type { ThymianConfig } from 'thymian'
```
TypeScript types are shipped with the package. Use the unscoped package name. The config interface is exported from 'thymian'.
ThymianResult
wrong
```
import { ThymianResult } from 'thymian'
```
correct
```
import type { ThymianResult } from 'thymian'
```
ThymianResult is a type-only export. Use 'import type' to avoid runtime issues.

Quickstart

Shows typical Thymian CLI commands: lint an OpenAPI spec, generate config, test a live endpoint, and analyze production traffic from a HAR file.

// 1. Run lint against an OpenAPI spec
const { execSync } = require('child_process');
const result = execSync('npx thymian lint --spec openapi:openapi.yaml', { encoding: 'utf-8' });
console.log(result);

// 2. Generate a config file
// Run: npx thymian generate config

// 3. Test a live endpoint
// Run: npx thymian test --spec openapi:openapi.yaml --target https://api.example.com

// 4. Analyze production traffic (requires HAR plugin)
// Run: npx thymian analyze --har traffic.har --spec openapi:openapi.yaml