CLI Reference¶

All commands share these global options:

Option	Description
`--project PATH`	Project root directory (default: current working directory).
`--config PATH`	Path to an explicit `pyproject.toml` config file.

init¶

Create a new Behave project from a template.

behave-gen init [OPTIONS] NAME

Arguments:

Argument	Description
`NAME`	New project directory name.

Options:

Option	Default	Description
`--template`	`default`	Template set to use.
`--template-engine`	`string`	Template engine: `string` or `jinja2`.
`--kit`	`false`	Pre-wire behave-kit in `environment.py`.
`--data`	`false`	Pre-wire behave-data hooks.
`--force`	`false`	Overwrite an existing directory.

Example:

behave-gen init my-project --kit --data

add feature¶

Add a .feature file to the project.

behave-gen add feature [OPTIONS] NAME

Arguments:

Argument	Description
`NAME`	Feature name (without extension).

Options:

Option	Default	Description
`--tags`	none	Comma or space separated tags.
`--template`	`default`	Feature template: `default` or `crud`.

Example:

behave-gen add feature login --tags smoke,auth
behave-gen add feature checkout --template crud

See Feature Templates.

add steps¶

Add real step definitions from a step library or generate them from a wavexis recording.

behave-gen add steps [OPTIONS]

Options:

Option	Default	Description
`--lib`	none	Step library name: `http` or `auth`.
`--from-recording`	none	Path to a wavexis recording YAML file. Generates step definitions and a feature file from recorded browser actions.

At least one of --lib or --from-recording must be provided. They can be combined: the library is added first, then recording-derived steps are deduplicated against it.

Examples:

# Add a built-in step library
behave-gen add steps --lib http
behave-gen add steps --lib auth

# Generate steps from a wavexis recording
behave-gen add steps --from-recording recording.yaml

# Combine library + recording (library first, then dedup)
behave-gen add steps --lib http --from-recording recording.yaml

See Step Libraries for the built-in libraries and Generating steps from a recording below.

Generating steps from a recording¶

Use wavexis to record browser interactions, then generate Behave step definitions and a feature file from the recording.

This produces:

features/steps/recorded_steps.py — Python step definitions with real browser actions via context.page (Playwright/wavexis page object).
features/recorded.feature — a Gherkin feature file representing the recorded flow.

Supported action types: navigate, click (by selector or text), type, and scroll. Unsupported actions are silently skipped. Steps are deduplicated against existing step definitions in the project.

add environment¶

Add or update environment.py with ecosystem hooks.

behave-gen add environment [OPTIONS]

Options:

Option	Default	Description
`--kit`	`false`	Add behave-kit fixtures.
`--data`	`false`	Add behave-data hooks.

Example:

behave-gen add environment --kit --data

add config¶

Add an ecosystem package to pyproject.toml.

behave-gen add config NAME

Arguments:

Argument	Description
`NAME`	Config to add: `behave-kit` or `behave-data`.

Example:

behave-gen add config behave-kit

from-openapi¶

Generate features and steps from an OpenAPI 3.x spec.

behave-gen from-openapi [OPTIONS] SPEC

Arguments:

Argument	Description
`SPEC`	Path to an OpenAPI 3.x spec (YAML or JSON).

Options:

Option	Default	Description
`--out-dir`	`gen`	Output directory for the generated project (creates a `features/` subdir).
`--step-lib`	none	Step library to bind (e.g. `http`).
`--tag`	none	Tag generated scenarios.
`--include-path`	all	Restrict to these paths (repeatable).
`--include-method`	all	Restrict to these HTTP methods (repeatable).

Example:

behave-gen from-openapi spec.yaml --out-dir gen --step-lib http --tag api
behave-gen from-openapi spec.yaml --include-path /pets --include-method GET

See Generators.

from-postman¶

Generate features and steps from a Postman collection.

behave-gen from-postman [OPTIONS] COLLECTION

Arguments:

Argument	Description
`COLLECTION`	Path to a Postman Collection v2.1 JSON file.

Options:

Option	Default	Description
`--out-dir`	`gen`	Output directory for the generated project (creates a `features/` subdir).
`--step-lib`	none	Step library to bind (e.g. `http`).
`--tag`	none	Tag generated scenarios.

Example:

behave-gen from-postman collection.json --out-dir gen --step-lib http --tag api

See Generators.

from-swagger¶

Generate features and steps from a Swagger 2.0 spec.

behave-gen from-swagger [OPTIONS] SPEC

Arguments:

Argument	Description
`SPEC`	Path to a Swagger 2.0 spec (JSON or YAML).

Options:

Option	Default	Description
`--out-dir`	`gen`	Output directory for the generated project (creates a `features/` subdir).
`--step-lib`	none	Step library to bind (e.g. `http`).
`--tag`	none	Tag generated scenarios.

Example:

behave-gen from-swagger swagger.json --out-dir gen --step-lib http --tag api

See Generators.

migrate¶

Migrate a Cucumber project to Behave.

behave-gen migrate [OPTIONS] SOURCE_DIR

Arguments:

Argument	Description
`SOURCE_DIR`	Cucumber project to migrate.

Options:

Option	Default	Description
`--out-dir`	`migrated`	Output directory for the migrated project (creates a `features/` subdir).

Example:

behave-gen migrate path/to/cucumber-project --out-dir migrated

See Cucumber Migration.

check¶

Check project health via behave-doctor.

behave-gen check [OPTIONS]

Options:

Option	Default	Description
`--format`	`text`	Output format: `text` or `json`.

Example:

behave-gen check
behave-gen check --format json

doctor¶

Alias for check.

behave-gen doctor

lint¶

Lint .feature files via behave-lint.

behave-gen lint [OPTIONS]

Options:

Option	Default	Description
`--fix`	`false`	Apply fixes where possible.
`--path`	features dir	Path to lint (repeatable); defaults to the features directory.

Example:

behave-gen lint
behave-gen lint --fix
behave-gen lint --path features/auth.feature

format¶

Format .feature files via behave-format.

behave-gen format [OPTIONS]

Options:

Option	Default	Description
`--check`	`false`	Check formatting without writing.
`--path`	features dir	Path to format (repeatable); defaults to the features directory.

Example:

behave-gen format
behave-gen format --check
behave-gen format --path features/auth.feature

preview¶

Preview a feature file with resolved examples and tables.

behave-gen preview [OPTIONS] FEATURE

Arguments:

Argument	Description
`FEATURE`	Path to a `.feature` file.

Example:

behave-gen preview features/login.feature

stats¶

Report project statistics.

behave-gen stats [OPTIONS]

Options:

Option	Default	Description
`--format`	`text`	Output format: `text` or `json`.

Example:

behave-gen stats
behave-gen stats --format json

update¶

Re-apply generated environment and step libraries to an existing project.

behave-gen update [OPTIONS]

Options:

Option	Default	Description
`--kit`	`false`	Include behave-kit wiring in `environment.py`.
`--data`	`false`	Include behave-data wiring in `environment.py`.
`--force`	`false`	Regenerate files even if they were user-modified.

Example:

behave-gen update --force

Files generated by behave-gen (marked with Generated by behave-gen) are refreshed. User-modified files without the marker are skipped unless --force is used.