CLI
===

The ``steplib`` command provides tools for inspecting and validating step
libraries without running behave.

.. code-block:: bash

   steplib --help

``steplib list``
----------------

List all registered steps, optionally filtered by category, backend or tag.

.. code-block:: bash

   steplib list
   steplib list --category api
   steplib list --backend httpx
   steplib list --tag smoke
   steplib list --json

Output (table mode):

.. code-block:: text

   PATTERN                                  CATEGORY  BACKEND  DESCRIPTION
   --------                                 --------  -------  -----------
   I send a {method} request to {url}       api       -        Send an HTTP request and store the response.
   the response status is {status:d}        api       -        Assert the last response status code.
   ...

Output (JSON mode, ``--json``):

.. code-block:: json

   [
     {
       "pattern": "I send a {method} request to {url}",
       "category": "api",
       "backend": null,
       "description": "Send an HTTP request and store the response.",
       "module": "steplib.modules.api.steps",
       "tags": [],
       "version": null,
       "deprecated": false,
       "example": "When I send a GET request to \"/users\"",
       "i18n": {
         "es": "envío una petición {method} a {url}",
         "pt": "envio uma requisição {method} para {url}"
       }
     }
   ]

Options
~~~~~~~

``--category, -c``
    Filter by category (e.g. ``api``, ``web``, ``db``, ``kafka``).

``--backend, -b``
    Filter by backend (e.g. ``httpx``, ``requests``, ``stdlib``, ``selenium``, ``sqlalchemy``).

``--tag, -t``
    Filter by tag.

``--json``
    Output as JSON instead of a table.

``steplib show``
----------------

Show detailed metadata for a single step pattern.

.. code-block:: bash

   steplib show "I send a {method} request to {url}"
   steplib show "I send a {method} request to {url}" --backend httpx
   steplib show "I send a {method} request to {url}" --json

Output (text mode):

.. code-block:: text

   Pattern:    I send a {method} request to {url}
   Category:   api
   Backend:    -
   Module:     steplib.modules.api.steps
   Function:   steplib.modules.api.steps.step_send_request
   Description: Send an HTTP request and store the response.
   Example:    When I send a GET request to "/users"
   Translations:
     [es] envío una petición {method} a {url}
     [pt] envio uma requisição {method} para {url}

Options
~~~~~~~

``--backend, -b``
    Filter by backend when the same pattern is registered for multiple
    backends.

``--json``
    Output as JSON.

``steplib validate``
--------------------

Validate that all registered steps satisfy the step contract.

.. code-block:: bash

   steplib validate

Checks performed:

1. **Patterns are parseable** by the ``parse`` library.
2. **Parameter names match** pattern placeholders — every declared ``Param``
   must appear in the pattern, and vice versa.
3. **No duplicate patterns** within the same backend.
4. **i18n translations** have the same placeholders as the base pattern, in
   the same order.
5. **Stacked patterns** (multiple ``@step`` decorators on the same function)
   share the same placeholders and order.
6. **Each step has a ``category``** — enforced by the dataclass, but
   double-checked.

Exit code is ``0`` if all checks pass, ``1`` if any errors are found.

``steplib init``
----------------

Generate a ``features/environment.py`` scaffold with ``autoload(context)``.

.. code-block:: bash

   steplib init
   steplib init --path my_features/environment.py

The generated file:

.. code-block:: python

   """behave environment generated by steplib init."""

   from steplib.behave import autoload

   def before_all(context):
       context.steplib = autoload(context)

   def before_scenario(context, scenario):
       context.steplib.reset()

   def after_scenario(context, scenario):
       context.steplib.cleanup()

Options
~~~~~~~

``--path, -p``
    Output path for ``environment.py``. Defaults to
    ``features/environment.py``. Parent directories are created
    automatically.

API reference
-------------

See :doc:`/api/core` for the full autodoc reference of ``steplib.cli.main``
and ``steplib.cli.formatters``.