Configuration File

This page is the canonical reference for Thymian configuration.

Where configuration is loaded from

Thymian resolves configuration in this order:

1. If you pass --config <path>, Thymian uses that file.
2. Otherwise, Thymian looks for thymian.config.yaml in --cwd (or your current directory).
3. If no file is found, Thymian uses built-in defaults.

Note

Thymian only checks thymian.config.yaml by default. If you want another filename or extension, pass it explicitly with --config.

Full configuration schema

See Configuration Schema for the complete list of supported keys, types, defaults, and descriptions.

Precedence and overrides

After loading config, CLI flags can override parts of it. Common overrides include:

• --spec <type:path> overrides specifications
• --traffic <type:path> overrides traffic
• --report <type:path> overrides reports (used by thymian report convert)
• --target-url <url> overrides targetUrl
• --rule-set <name> extends ruleSets at runtime (appends and deduplicates)
• --rule-severity <off|error|warn|hint> overrides ruleSeverity
• --log-level <trace|debug|info|warn|error|silent> overrides logLevel
• --debug effectively overrides logLevel to debug
• --verbose effectively overrides logLevel to info
• --autoload/--no-autoload controls plugin autoloading

Generated baseline config

thymian generate config creates a config based on built-in defaults plus your selected specification(s).

Typical generated baseline:

specifications:
  - type: openapi
    location: ./openapi.yaml

traffic: []

ruleSets:
  - '@thymian/rules-rfc-9110'
  - '@thymian/rules-api-description-validation'

ruleSeverity: error
rules: {}

plugins:
  '@thymian/plugin-http-linter': {}
  '@thymian/plugin-openapi': {}
  '@thymian/plugin-request-dispatcher': {}
  '@thymian/plugin-sampler': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {}
  '@thymian/plugin-http-tester': {}
  '@thymian/plugin-http-analyzer': {}
  '@thymian/plugin-har': {}
  '@thymian/plugin-spectral': {}

Workflow-specific examples

Static linting only

specifications:
  - type: openapi
    location: ./openapi.yaml

ruleSets:
  - '@thymian/rules-rfc-9110'

plugins:
  '@thymian/plugin-http-linter': {}
  '@thymian/plugin-openapi': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {}

Live API testing

specifications:
  - type: openapi
    location: ./openapi.yaml

targetUrl: http://localhost:3000

ruleSets:
  - '@thymian/rules-rfc-9110'

plugins:
  '@thymian/plugin-openapi': {}
  '@thymian/plugin-request-dispatcher': {}
  '@thymian/plugin-sampler': {}
  '@thymian/plugin-http-tester': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {}

Convert external reports

reports declares the pre-generated external reports that thymian report convert imports; the optional specifications entries let the converter map findings onto your API description. --report flags replace the reports entries, exactly like --spec replaces specifications.

reports:
  - type: spectral
    location: ./report.json

specifications:
  - type: openapi
    location: ./openapi.yaml

plugins:
  '@thymian/plugin-openapi': {}
  '@thymian/plugin-spectral': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {}

See Importing Spectral results for the full flow.

Analyze recorded traffic

traffic:
  - type: fixture
    location: static

ruleSets:
  - '@thymian/rules-rfc-9110'

plugins:
  '@thymian/plugin-http-analyzer': {}
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {}

Report formatters

@thymian/plugin-reporter writes one file per configured formatter. Each formatter accepts an optional path: a relative path is resolved against --cwd, and an absolute path is used as-is.

plugins:
  '@thymian/plugin-reporter':
    options:
      formatters:
        markdown: {} # .thymian/reports/report.md
        csv:
          path: reports/findings.csv
        json: {} # .thymian/reports/report.json

Formatter	Default path	Use it for
markdown	.thymian/reports/report.md	Human review, PR comments, CI job summaries
csv	.thymian/reports/report.csv	Tabular analysis in spreadsheets or BI tools
json	.thymian/reports/report.json	Automation and post-processing of the full report data

When to use the Markdown formatter

Pick markdown when a person or AI agent reads the result — in a pull request, a CI job summary, or locally:

• Review in GitHub: the document uses inline HTML (<details> blocks, a <sub> legend, colored <span> counts), so it pastes straight into a PR comment or $GITHUB_STEP_SUMMARY.
• Triage at a glance: a severity roll-up, a per-run outcome table, and lint findings grouped under the endpoint they belong to.
• Failures only: passed test cases and passed executions without findings are left out, so the document stays focused on what needs attention.

Locations are resolved to readable endpoint strings such as POST /orders - application/json → 201 CREATED, and the raw request/response of a failed test step is tucked into a nested <details> block. Table cells are single-line, so multi-line messages are flattened, and expected/actual values are folded into the message rather than kept as fields.

When to use the CSV formatter

Pick csv when you want to sort, filter, or pivot results in a spreadsheet or BI tool:

• Tabular analysis: thirteen fixed columns, one record per line, nothing nested to unwrap.
• Complete outcome tally: unlike markdown, every execution gets a row — passed, failed, and skipped alike — so you can compute pass rates instead of only counting failures.
• Two row types: a row_type=execution row carries the outcome (status and resolved severity), and each row_type=finding row beneath it carries one assertion or informational detail.

The columns are run_id, run_type, tool, rule_id, location, row_type, status, severity, finding_kind, finding_id, title, message, and detail. Structured values are flattened into detail as key=value pairs (expected=200; actual=404). HTTP transactions are not included.

When to use the JSON formatter

Pick json when code — rather than a reader — consumes the output, and you need the complete report:

• Post-processing and integrations that would otherwise have to parse markdown or CSV.
• Archiving a run so its full result set can be re-examined later.
• Detail the other formatters omit, such as passed executions, finding identifiers, run-level artifacts and invocations, and the serialized Thymian format graph that locations reference.

The file contains the canonical report payload exactly as Thymian emitted it on the core.report event, with no presentation transforms applied. The top level is always a JSON array of report objects, so a session that produces several reports stays complete. A single-workflow run yields a one-element array.

Locations are stored as references, not rendered endpoint strings: a thymianFormat location carries elementId/elementType that you resolve against the run’s entry in the report’s thymianFormat map (selected by ToolRun.thymianFormatVersion).

Validation behavior and failure modes

If config parsing or schema validation fails, the CLI exits with code 2 and prints an error.

Common issues:

1. Unsupported file extension when loading with --config
2. Invalid YAML/JSON syntax
3. Invalid value types (for example non-array ruleSets)
4. Unknown or misspelled top-level keys — the schema only allows the documented keys and rejects anything else
5. Missing specification with commands that require one

Practical tips

• Prefer thymian generate config to bootstrap a correct baseline.
• Keep plugin configuration minimal first, then add plugin options incrementally.
• Use --spec for one-off checks without editing files.
• Keep ruleSeverity: error in CI unless you explicitly want warnings/hints to gate builds.

Related pages

• Understanding the Configuration File — quick overview in the Getting Started guide
• Use thymian lint workflow
• Use thymian test workflow
• Use thymian analyze workflow
• Importing Spectral results