Introduction

gherkin-cli is an agent-first Gherkin CLI: parse, validate, and diff .feature files with token-efficient, AXI-conformant output. It wraps the canonical @cucumber/gherkin parser — the tool never hand-rolls Gherkin tokenization — and projects the result through a compact, deterministic output layer built for AI agents that read and reason over Gherkin suites.

It ships two surfaces over the same three capabilities: a CLI you run and a programmatic API you import. The CLI Reference documents the commands; the API Reference documents the pure engines (parse, validate, diff) you call directly, with no stream write and no process.exit.

The three capabilities:

• parse — project a .feature into a compact digest: scenario names, tags, and counts.
• validate — check .feature well-formedness, with a gating exit code for CI.
• diff — classify scenario changes against a git ref (added / modified / removed / unchanged), with an addOnly aggregate for purely-additive changes.

Bare invocation (gherkin-cli with no arguments) is not a usage manual — it prints the live .feature inventory of the current directory, so an agent can act on what it sees in one call.

Try it

# What .feature files are here, and how many scenarios does each have?
npx gherkin-cli

# Project a suite into a compact digest
npx gherkin-cli parse features/**/*.feature

Where next

• Installation — running gherkin-cli via npx or installing it into a project.
• CLI Reference — parse, validate, and diff in full.
• API Reference — the same capabilities as pure functions you import.
• AXI output contract — the agent-facing output contract every command follows.
• TOON format — the compact default output encoding.