The interactive shell
Running bdd with no subcommand in a terminal opens a REPL. It prints
the help once, shows the banner and the session’s model status, and
then reads commands until you leave.
bdd> spec list
[
{ "id": "REQ-001", "title": "Empty string returns zero", "status": "implemented" }
]
bdd> test --feature features/calculator.feature
...
bdd> exit
Behavior
- No prefix needed. Type
spec list, notbdd spec list. A leadingbddis forgiven if you type it anyway. - Inherited flags. Commands inherit the shell’s
--rootand--modelunless the line supplies its own:
bdd --root ~/code/calculator --model qwen3-coder-next:latest
# every command in this shell now targets that root and model
- Quoting works. Lines are tokenized with shell rules, so
scenario add --step "Given a calculator"behaves as expected. Unbalanced quotes reportunreadable inputand the shell continues. - Errors don’t kill the shell. A failing command prints its error and returns to the prompt.
- Blank lines are ignored.
Leaving
exitorquit- Ctrl+C (interrupt)
- Ctrl+D (end of input)
On exit the shell prints a summary of how many commands ran.
Session history
Line history is kept across sessions in .bdd-history under the
project root. Use ↑/↓ to recall previous
commands and Ctrl+R for reverse search. If the
history cannot be saved, the shell says so and exits normally.
Model announcement at startup
The first prompt is preceded by one line describing the session’s
model. This CLI is developed and run against
qwen3-coder-next:latest; your mileage will vary with a different
model, especially one trained for work other than development. See
Getting started and
bdd model.
| Situation | Announcement |
|---|---|
Configured in .bdd-mcp.toml | Model set: qwen3-coder-next:latest (from configuration). |
| No config, models installed | Model set for this session: qwen3-coder-next:latest (not saved - keep it with: bdd model use qwen3-coder-next:latest). |
| Ollama up, no models | Ollama is running but has no models - generation will use deterministic templates. For optimal results pull a coding model, e.g.: ollama pull qwen3-coder-next:latest (mileage varies with models not trained for development) |
| Ollama unreachable | Ollama is not reachable - generation will use deterministic templates. Install it from https://ollama.com, start it, and pull a coding model, e.g.: ollama pull qwen3-coder-next:latest (mileage varies with models not trained for development) |
The greenfield nudge
When all three signs of a brand-new project line up —
- this is the first shell session in the root (no
.bdd-historyyet), - a model is ready, and
- there is no
requirements/requirements.json
— the shell offers to start the loop before the first prompt:
It appears you are in a greenfield - this project has no requirements/requirements.json yet.
Start with the greenfield command now? [y/N]
y runs bdd greenfield immediately;
anything else declines and the shell carries on:
No problem - type greenfield any time, or spec draft to begin with the spec.
When there is no terminal
If stdin is not a terminal (piped input, CI), bare bdd prints the
help and exits instead of opening the shell.