Command reference
gherkin-ai and ghk are the same binary. Run ghk <command> --help for the authoritative list of options.
Global options:
--project <dir>: target project, skipping workspace detection;--yes/--non-interactive: never prompt (also implied by--json,CI=trueand a stdin that is not a terminal);--spec-dir <dir>: where the.featurefiles are;--json: exactly one JSON document on stdout;--verbose/--quiet: logging level;--dry-runand--stdout: for commands that write files.
-f/--feature takes a path or the name of a feature in the spec directory (orders, orders.feature), the same in every command. A name that matches no feature exits 2 and lists the ones there are (lint keeps reporting a missing path as GHK000, exit 4).
Exit codes are listed in ENTERPRISE.md §5.
Specification
| Command | Purpose | Main options |
|---|---|---|
create (c, new) |
Write a feature interactively, or headless from a JSON file | -o <file>, --headless --config <file>, -C (single prompt) |
speckit import |
Convert GitHub Spec Kit specs/NNN-*/spec.md into .feature files |
--dir <specs>, --out <features>, --force |
speckit export |
Write .feature files as Spec Kit specs |
--out <specs>, --force |
speckit verify |
Every Spec Kit story, FR-### and completed task has a scenario, and the code converges; exit 7 on drift (ENTERPRISE.md §16) | --dir <specs>, --out <features>, --threshold <0-100>, --json |
lint |
Specification quality rules and score, plus the industry rules when industry.id is set |
-f <file>, --threshold <0-100> (exit 4 below), --rules, --all (every project in the repo), --explain-ir (aggregate, route, commands and events, and where each name comes from), --allow-empty (no feature files is not exit 2), --assist (the configured LLM proposes @aggregate/@command/@event tags where GHK016 finds no names; validated against naming rules and the code's type names, written as .ghe/patches/*.patch; the lint result is unchanged) |
industry list / show <id> / apply <id> |
Industry profiles: list them, show one (standards, vocabulary, rules, agent guidance), or opt the project in (sets industry.id, writes .ghe/industry-context.*). See INDUSTRIES.md |
--json |
validate (v) |
Specification and architecture rules; optional OpenAPI / AsyncAPI comparison. With -f, also the steps of the feature that no step definition matches (TypeScript/JavaScript, Java/Kotlin, Python, C#, Ruby; generated pending steps count as defined) |
-f, --openapi <file>, --asyncapi <file>, -t <dir>, --strict-steps (undefined steps fail, exit 4) |
export (e) |
Agent context bundle for one feature | -f, --format md|json, -o |
lang |
CLI interaction language (en, es). Generated prompts stay in English. |
-s <locale> |
Generation
| Command | Purpose | Main options |
|---|---|---|
init (i) |
Create gherkin-ai.config.json for a new project. Refuses (exit 2) when one exists; in an existing project use detect |
-l, -f, -o, -d, -m, --frameworkVersion, --ormVersion, --frontendFramework, --industry <id>, --enterprise, --force (replace the configuration and .ghkgovernance.yaml) |
stacks |
Supported stacks and their tier | --json |
generate (g) |
Contracts, domain kernel, tests, runtime, application layer and prompts for a feature. Never overwrites edited or protected files (writes <file>.ghk-new). The runtime kernel is written as a unit: while a kernel file is kept, the generated source files are held as .ghk-new too, so the project still compiles. In a project marked .ghk-implemented, only the kernel and the contracts are created (skipped otherwise). generation.exclude globs are never written (gitignore style: openapi.json matches at any depth, /openapi.json only at the root). --review shows each .ghk-new diff and takes the generated version or keeps yours (a kept version is not offered again; non-interactive: exit 4 while versions are pending) |
-f <file>, -c <config>, --force, --dry-run, --json (the write plan: file, action, role, reason), --include-scaffold, --contracts-only (only OpenAPI, AsyncAPI, gRPC, GraphQL and the ADR), --review, --accept-new, --keep-mine |
add (a) |
Inject contracts and prompts into an existing module (brownfield); TypeScript projects also get a contract and it.todo tests. Edited files are kept (<file>.ghk-new) |
-f, -t <dir> (required outside NestJS) |
detect (d) |
Detect the stack of an existing project and write gherkin-ai.config.json from it, with outputDir: ./generated-specs |
--json (report the detected stack, write nothing) |
upgrade |
Assisted upgrade of a project generated by an older version, on a new branch | --apply, --check (exit 4), --commit, --branch, --no-git, --no-regenerate, --prune, --cli, --force, --kernel (refresh only the runtime kernel), --all, --dry-run |
ghk upgrade never changes the current branch and never pushes. See MIGRATION-3.2.md, and ADOPTION.md for projects gherkin-ai did not generate.
Verification and governance
| Command | Purpose | Main options |
|---|---|---|
converge (conv) |
Spec-to-code convergence across seven dimensions (coverage is n/a without a report), plus pass/fail contract checks: the feature changed since its contracts were generated (spec-changed), contract operations the running service does not serve (live-contract, with --live), states the feature names that no contract enum lists (spec-states). A failing check exits 7 whatever the score. The score measures how artifacts line up, not behaviour: run the tests for that |
-f, --threshold (exit 7 below), --all, `--live <file |
diff |
Drift between a feature and a DTO or contract | -f, -t <file> |
impact |
Files affected by a change to a feature | -f |
risk |
Delivery risk of a change: LOW / MEDIUM / HIGH / CRITICAL, with evidence. Weights from policy.risk.weights; --calibrate proposes them from the git history |
--base <ref>, --files <list>, --fail-on <level> (exit 4), --calibrate, --commits <n>, --write |
report |
Publishes lint, convergence and delivery risk on the pull / merge request. GitHub: annotations on the .feature lines and a job summary. GitLab: a Code Quality report. No token needed | --provider github|gitlab, --base <ref>, --threshold <score>, --fail-on <level> (exit 4), --out <file> |
graph |
Traceability graph: feature → scenario → command / event / endpoint → files and tests (also @trace:<Symbol> tags, ghk:implements <Symbol> comments, where the aggregate name links to its feature, and ghk:trace feature=<path> comments). --serve opens the live graph in the browser (127.0.0.1, token-protected, rebuilt on every reload; click a node to trace it) |
--trace <symbol>, --scope <feature>, --format summary|json|mermaid|dot, -o, --serve, --port |
firewall check |
Would the firewall allow an agent action? | [command] (same as --exec), --write <path>, --exec <cmd>, --network <host>, --secret <name>, --tool <name>, -f <feature> (exit 5 unless ALLOW) |
firewall policy |
Effective firewall rules, including a feature's scope | -f <feature> |
firewall hook |
Claude Code PreToolUse hook (reads the tool call on stdin) |
-f <feature> |
verify (v-loop) |
Run the tests; optionally let an LLM propose fixes. With --auto-fix, mechanical failures (missing dependency, out-of-sync lockfile) are fixed with the toolchain's dependency command first, and failures that are not code bugs (no database or broker, pending .ghk-new versions) stop with an explanation instead of a model call |
-c <cmd>, --docker, --docker-network, --auto-fix, --apply, --max-retries, --allow-unattended-writes, --force-branch, -f <feature> (with --auto-fix: the agent may only write inside that feature's impact scope), --host (with --auto-fix: run on this machine; by default the repair loop runs in the sandbox container, and LLM, cloud and registry credentials are always left out of its environment), --services (integration suite against PostgreSQL and the broker of stack.messaging), --converge-threshold <score> (after passing tests, exit 7 below this convergence; otherwise the score is only reported), --isolated (deprecated alias of --services) |
quality (q) |
Runs the tests with coverage and scores delivery risk; exit 4 when the gate fails. Failing tests always fail it; no coverage figure fails it unless --allow-missing-coverage. Without a change set (no --base, clean tree) the risk is reported but does not gate. The tests run with the stack default command, or with coverage.command writing coverage.report when the project measures coverage its own way (e.g. integration tests that need a database) |
--json (with coverage.command, commandSource, warning, exitCode, reportMtime), --base <ref>, --allow-missing-coverage |
evaluate (eval) |
File and class size, and pattern compliance | --max-file-lines, --max-class-lines |
pr-review |
Check a diff against a feature | -f, --diff <file> |
bench init / bench run |
A/B benchmark of your agent with and without gherkin-ai | --agent <cmd>, --repetitions, --arms, --out, --dry-run |
verify --docker runs the tests in the stack's toolchain image, in outputDir when the command is the toolchain's:
- no network (
--docker-network bridgewhen dependencies must be downloaded); - 2 GB of memory, 2 CPUs and 512 processes;
- all capabilities dropped and a read-only root filesystem;
- the toolchain's dependency caches as writable named volumes (
ghk-cache-<name>).
verify --services adds PostgreSQL, RabbitMQ and the broker of stack.messaging (Pub/Sub or Service Bus emulator, Kafka), the same containers as the golden builds. It runs in the image's own disposable root with default capabilities, because the stacks' dependency installers write into system directories; the limits and no-new-privileges stay. Override the limits in sandbox.*; sandbox.services adds containers of your own.
Agents
| Command | Purpose | Main options |
|---|---|---|
implement (impl) |
Implementation prompt and context package for a feature | -f, --docker, -C (compact), --no-audit, --inventory |
context |
Write project conventions and security notes into .ghe/ |
– |
mcp |
Start the MCP server (stdio, read-only by default) | – |
mcp install |
Register the server, version-pinned, in MCP clients | – |
skill (s) |
IDE rules files (.cursorrules and others) |
– |
autopilot (auto) |
Experimental: requirement → spec → code → verify loop | -r <file>, --apply, --allow-unattended-writes, --force-branch, --host, --services (PostgreSQL + RabbitMQ integration suite) |
agent-log |
Record or list actions taken by an agent | -a <text>, -f, -l, --clear |
web (w, ui) |
Local Web Studio (token-protected, localhost only) | -p <port> |
doc (site) |
Static documentation site from the features | – |
verify --auto-fix --apply and autopilot --apply write files only after these guards pass:
- the CI guard and the protected-branch guard;
- the agent firewall: files it does not allow become unified-diff proposals,
.ghe/patches/<path with / as __>.patch(git applytakes one); - in the repair loop, specifications, contracts and tests need a human: the loop changes the implementation, not what it is checked against.
If the loop ends without passing tests (retry limit, circuit breaker, a stop rule, an error), every file it wrote is restored and every file it created is removed.
Configuration, credentials and audit
| Command | Purpose | Main options |
|---|---|---|
config show |
Effective configuration | --sources (which layer set each value), --json |
config validate / config schema |
Validate the configuration layers, or print the JSON Schema | -c <file> |
login |
Store a provider API key in the OS keychain | --provider <name>, --api-key-stdin |
logout |
Remove stored keys | --provider <name> |
auth status |
Provider, model, credential source, endpoint, proxy (never the secret) | --json |
audit (inventory) |
Feature inventory and history | -f, --json, --html, --clear |
audit export |
Security audit trail for a SIEM | --format jsonl|csv|ocsf (OCSF 1.3 API Activity events), --since 7d, -o |
sbom |
CycloneDX SBOM of the project | – |