Configuration¶

behave-format is opinionated — it works out of the box with zero configuration. But when you need to customize, all settings live in pyproject.toml under [tool.behave-format].

Quick reference¶

[tool.behave-format]
indent = 2
sort_tags = true
sort_features = false
sort_scenarios = false
line_length = 120

Options¶

`indent`¶


Type	`int`
Default	`2`
CLI flag	`--indent N`

Number of spaces for indentation. Must be a positive integer.

[tool.behave-format]
indent = 4

# Override from CLI
behave-format --indent 4 features/

`sort_tags`¶


Type	`bool`
Default	`true`

Sort tags alphabetically within each tag group (Feature-level and Scenario-level).

[tool.behave-format]
sort_tags = false  # preserve original tag order

`sort_features`¶


Type	`bool`
Default	`false`

Sort features alphabetically by name within a project.

Use with caution

Sorting features changes the order of files in your project. This may affect test execution order.

`sort_scenarios`¶


Type	`bool`
Default	`false`

Sort scenarios alphabetically by name within each feature.

`line_length`¶


Type	`int`
Default	`120`

Maximum line length for reference. Currently used as a guideline — the formatter does not hard-wrap long lines, but future versions may use this for smart wrapping.

Configuration precedence¶

Settings are resolved in the following order (highest to lowest):

CLI flags (--indent) — override everything
pyproject.toml ([tool.behave-format]) — project-level defaults
Built-in defaults — sensible fallbacks

# pyproject.toml says indent=2, but CLI overrides to 4
behave-format --indent 4 features/

Custom config file¶

By default, behave-format auto-discovers pyproject.toml in the current directory. You can specify a custom path:

behave-format --config path/to/custom-pyproject.toml features/

Programmatic configuration¶

from behave_format import Settings

# Default settings
settings = Settings()

# Custom settings
settings = Settings(
    indent=4,
    sort_tags=True,
    sort_features=False,
    sort_scenarios=True,
    line_length=100,
)

# From a dict
settings = Settings.from_dict({"indent": 4, "sort_tags": False})

# From pyproject.toml
settings = Settings.from_pyproject("pyproject.toml")

# Immutable override
settings = Settings(indent=2)
settings = settings.with_indent(4)  # returns new Settings with indent=4

Settings are immutable

Settings is a frozen dataclass. Once created, you cannot modify its attributes directly. Use with_indent() or create a new instance.

Environment-specific configs¶

You can maintain multiple config files for different environments:

# Development (2-space indent)
behave-format --config pyproject.dev.toml features/

# Production (4-space indent)
behave-format --config pyproject.prod.toml features/

Example configurations¶

Minimal (defaults)StandardStrictPreserve order

# pyproject.toml — no [tool.behave-format] section needed
# All defaults apply: indent=2, sort_tags=true, etc.

[tool.behave-format]
indent = 2
sort_tags = true
sort_features = false
sort_scenarios = false
line_length = 120

[tool.behave-format]
indent = 4
sort_tags = true
sort_features = true
sort_scenarios = true
line_length = 100

[tool.behave-format]
indent = 2
sort_tags = false
sort_features = false
sort_scenarios = false
line_length = 120