feat(repl): --backend flag to force a specific input backend

Lets you exercise the readline (or plain) code path without
uninstalling the prompt_toolkit extra:

    robotcode repl --backend=readline

Values: auto (default cascade), prompt-toolkit, readline, plain.
Also available as `ROBOTCODE_REPL_BACKEND`.

When the requested backend isn't importable on the current Python,
startup aborts with a clear error and a `pip install` hint — there
is no silent fallback, so the explicit choice is always honoured
(or visibly refused).

`--plain` stays as a shorthand for `--backend=plain`; combining it
with a non-`plain` `--backend` value is rejected as a usage error.

Author: d-biehl

docs/03_reference/repl.md

@@ -83,9 +83,22 @@ Log To Console    answer is ${x}
 
 The prompt is a real line editor — arrow-keys for cursor movement, `Ctrl-R` for reverse history search, Tab for Robot-aware completion. On Unix and on Windows with Python 3.13+ this is wired up out of the box via Python's stdlib `readline`; on older Windows Pythons you only get plain `input()` unless you install `pyreadline3`.
 
-### Disabling all enhancements (AI agents, automation)
+### Picking a specific input backend
 
-Pass `--plain` (or set `ROBOTCODE_REPL_PLAIN=1`) to bypass every layer above and fall back to a bare `input()` prompt. That means no history, no completion, no candidate popup, no auto-suggest, no syntax highlighting — just a plain line read. Use this for AI-agent invocations or automation pipelines where ANSI escape sequences and completion popups would corrupt stdin/stdout capture.
+The REPL auto-picks the best available input backend on startup (`prompt_toolkit` → `readline` → bare `input()`). Pass `--backend` (or set `ROBOTCODE_REPL_BACKEND`) to force a specific one:
+
+| Value | Effect |
+| ----- | ------ |
+| `auto` (default) | Run the fallback cascade. |
+| `prompt-toolkit` | Use the prompt_toolkit backend. Requires the `[prompt-toolkit]` extra. |
+| `readline` | Use the readline backend even when prompt_toolkit is installed. Useful for testing the readline code path or for users who prefer it. |
+| `plain` | Bypass every editor layer and fall back to a bare `input()` prompt. |
+
+Requesting a backend that isn't importable on the current Python aborts startup with a clear error and a `pip install` hint — there is no silent fallback, so the explicit choice is always honoured (or visibly refused).
+
+#### Disabling all enhancements (AI agents, automation)
+
+`--plain` (or `ROBOTCODE_REPL_PLAIN=1`) is a shorthand for `--backend=plain`. It bypasses every layer above and falls back to a bare `input()` prompt — no history, no completion, no candidate popup, no auto-suggest, no syntax highlighting. Use this for AI-agent invocations or automation pipelines where ANSI escape sequences and completion popups would corrupt stdin/stdout capture.
 
 ```bash
 # AI-agent style: pipe input, capture clean output
@@ -94,7 +107,7 @@ Log To Console    hello from agent
 EOF
 ```
 
-`--plain` and `--no-history` can be combined safely (plain mode has no history file anyway).
+Combining `--plain` with a non-`plain` `--backend` value is rejected as a usage error; combining it with `--no-history` is fine (plain mode has no history file anyway).
 
 ### History across sessions
 

packages/repl/src/robotcode/repl/_input/__init__.py

@@ -1,7 +1,7 @@
 """Backend abstraction for the REPL's interactive line-input.
 
-`pick_backend()` walks a fallback cascade and returns the best
-available implementation:
+`pick_backend()` picks an explicit backend when one is named, else
+walks a fallback cascade and returns the best available implementation:
 
 1. `PromptToolkitBackend` — if `prompt_toolkit>=3.0` is installed.
 2. `ReadlineBackend` — if `readline` is importable (stdlib on Unix,
@@ -17,6 +17,14 @@
 from ._plain import PlainBackend
 
 
+class BackendUnavailableError(ImportError):
+    """Raised when an explicitly requested backend cannot be imported.
+
+    Subclasses `ImportError` so callers can catch either — `cli.py`
+    translates it into a `click.UsageError` with a `pip install` hint.
+    """
+
+
 class InputBackend(Protocol):
     """Protocol every line-input backend implements."""
 
@@ -72,8 +80,11 @@ def delete_history_entry(self, idx: int) -> bool:
         ...
 
 
-def pick_backend(*, no_history: bool = False, plain: bool = False) -> InputBackend:
-    """Return the best available input backend.
+BACKEND_CHOICES = ("auto", "prompt-toolkit", "readline", "plain")
+
+
+def pick_backend(*, no_history: bool = False, backend: str = "auto") -> InputBackend:
+    """Return an input backend.
 
     Parameters
     ----------
@@ -82,35 +93,59 @@ def pick_backend(*, no_history: bool = False, plain: bool = False) -> InputBacke
         and saving the persistent history file — in-session arrow-up
         recall still works, but nothing crosses session boundaries.
         PlainBackend is unaffected (it has no history either way).
-    plain:
-        When True, bypass the cascade entirely and return PlainBackend.
-        Disables completion, syntax highlighting, popup, auto-suggest,
-        history — the prompt becomes a bare `input()`. Recommended for
-        AI-agent invocations and automation pipelines where ANSI
-        escapes or completion popups would corrupt stdout capture.
-
-    The PlainBackend is always returnable, so this function never raises.
+    backend:
+        One of ``"auto"``, ``"prompt-toolkit"``, ``"readline"``,
+        ``"plain"``. ``"auto"`` runs the fallback cascade. The other
+        values force a specific backend and raise
+        `BackendUnavailableError` when that backend can't be imported
+        — no silent fallback, so the caller learns that the explicit
+        choice was not honoured.
     """
-    if plain:
+    if backend == "plain":
         return PlainBackend()
 
-    # PromptToolkit (Stage 3) — wins if the user installed the extra.
-    try:
-        from ._prompt_toolkit import PromptToolkitBackend  # type: ignore[import-not-found,import-untyped,unused-ignore]
-    except ImportError:
-        pass
-    else:
+    if backend == "prompt-toolkit":
+        try:
+            from ._prompt_toolkit import (
+                PromptToolkitBackend,  # type: ignore[import-not-found,import-untyped,unused-ignore]
+            )
+        except ImportError as exc:
+            raise BackendUnavailableError(
+                "prompt_toolkit backend requested but not installed. "
+                "Install with: pip install 'robotcode-repl[prompt-toolkit]'"
+            ) from exc
         return PromptToolkitBackend(no_history=no_history)  # type: ignore[no-any-return,unused-ignore]
 
-    # Readline (Stage 1+2) — stdlib on Unix, PyREPL on Win 3.13+.
-    try:
-        from ._readline import ReadlineBackend
-    except ImportError:
-        pass
-    else:
+    if backend == "readline":
+        try:
+            from ._readline import ReadlineBackend
+        except ImportError as exc:
+            raise BackendUnavailableError(
+                "readline backend not available on this Python build. "
+                "Install with: pip install 'robotcode-repl[gnureadline]'"
+            ) from exc
         return ReadlineBackend(no_history=no_history)
 
-    return PlainBackend()
+    if backend == "auto":
+        try:
+            from ._prompt_toolkit import (
+                PromptToolkitBackend,  # type: ignore[import-not-found,import-untyped,unused-ignore]
+            )
+        except ImportError:
+            pass
+        else:
+            return PromptToolkitBackend(no_history=no_history)  # type: ignore[no-any-return,unused-ignore]
+
+        try:
+            from ._readline import ReadlineBackend
+        except ImportError:
+            pass
+        else:
+            return ReadlineBackend(no_history=no_history)
+
+        return PlainBackend()
+
+    raise ValueError(f"Unknown backend: {backend!r}. Choose from {BACKEND_CHOICES}.")
 
 
-__all__ = ["InputBackend", "PlainBackend", "pick_backend"]
+__all__ = ["BACKEND_CHOICES", "BackendUnavailableError", "InputBackend", "PlainBackend", "pick_backend"]

packages/repl/src/robotcode/repl/cli.py

@@ -6,6 +6,7 @@
 from robotcode.plugin import Application, pass_application
 
 from .__version__ import __version__
+from ._input import BACKEND_CHOICES, BackendUnavailableError
 from .console_interpreter import ConsoleInterpreter
 from .run import run_repl
 
@@ -60,16 +61,30 @@
     "Useful for AI-agent invocations or quick spike sessions you don't "
     "want polluting your shell's REPL history.",
 )
+@click.option(
+    "--backend",
+    type=click.Choice(list(BACKEND_CHOICES)),
+    default="auto",
+    show_default=True,
+    envvar="ROBOTCODE_REPL_BACKEND",
+    help="Force a specific input backend instead of auto-picking. "
+    "`auto` runs the fallback cascade (prompt-toolkit → readline → plain). "
+    "Use the explicit values to test the readline / plain code paths "
+    "even when `prompt_toolkit` is installed. Requesting a backend that "
+    "is not available aborts startup with a clear error — no silent "
+    "fallback.",
+)
 @click.option(
     "--plain",
     is_flag=True,
     default=False,
     envvar="ROBOTCODE_REPL_PLAIN",
-    help="Disable all prompt enhancements — completion, syntax highlighting, "
-    "candidate popup, auto-suggest, history file. The prompt becomes a bare "
-    "`input()` call. Recommended for AI-agent invocations, automation "
-    "pipelines, and any context where ANSI escapes or completion popups "
-    "would interfere with stdin/stdout capture.",
+    help="Shorthand for `--backend=plain`. Disables all prompt enhancements — "
+    "completion, syntax highlighting, candidate popup, auto-suggest, history "
+    "file. The prompt becomes a bare `input()` call. Recommended for "
+    "AI-agent invocations, automation pipelines, and any context where ANSI "
+    "escapes or completion popups would interfere with stdin/stdout capture. "
+    "Conflicts with `--backend=<other>`.",
 )
 @click.option(
     "-d",
@@ -133,6 +148,7 @@ def repl(
     show_keywords: bool,
     inspect: bool,
     no_history: bool,
+    backend: str,
     plain: bool,
     outputdir: Optional[str],
     output: Optional[str],
@@ -148,14 +164,22 @@ def repl(
     if files:
         files = tuple(f.absolute() for f in files)
 
-    interpreter = ConsoleInterpreter(
-        app,
-        files=list(files),
-        show_keywords=show_keywords,
-        inspect=inspect,
-        no_history=no_history,
-        plain=plain,
-    )
+    if plain and backend not in ("auto", "plain"):
+        raise click.UsageError(f"--plain conflicts with --backend={backend}. Use one or the other.")
+    if plain:
+        backend = "plain"
+
+    try:
+        interpreter = ConsoleInterpreter(
+            app,
+            files=list(files),
+            show_keywords=show_keywords,
+            inspect=inspect,
+            no_history=no_history,
+            backend=backend,
+        )
+    except BackendUnavailableError as exc:
+        raise click.UsageError(str(exc)) from exc
 
     run_repl(
         interpreter=interpreter,

packages/repl/src/robotcode/repl/console_interpreter.py

@@ -23,7 +23,7 @@ def __init__(
         show_keywords: bool = False,
         inspect: Optional[bool] = False,
         no_history: bool = False,
-        plain: bool = False,
+        backend: str = "auto",
     ) -> None:
         super().__init__()
 
@@ -33,7 +33,7 @@ def __init__(
         self.inspect = inspect
 
         self.executed_files: List[Path] = []
-        self._input: InputBackend = pick_backend(no_history=no_history, plain=plain)
+        self._input: InputBackend = pick_backend(no_history=no_history, backend=backend)
         # REPL inputs that parsed cleanly — `.save` exports them as a
         # runnable `.robot` file. Each entry may be multi-line.
         self._session_lines: List[str] = []

tests/robotcode/repl/test_backends.py

@@ -121,33 +121,74 @@ def test_pick_backend_prefers_prompt_toolkit_when_available() -> None:
 
 
 # ---------------------------------------------------------------------------
-# --plain escape hatch — forces PlainBackend regardless of installed extras.
+# Explicit `backend=` selection — forces a specific backend, errors on miss.
 # ---------------------------------------------------------------------------
 
 
 def test_pick_backend_plain_returns_plain_even_with_prompt_toolkit() -> None:
-    """`plain=True` must bypass the cascade — no popup, no readline, no
-    ANSI codes leaking into AI-agent stdout capture."""
-    backend = pick_backend(plain=True)
+    """`backend="plain"` bypasses the cascade — no popup, no readline,
+    no ANSI codes leaking into AI-agent stdout capture."""
+    backend = pick_backend(backend="plain")
     assert isinstance(backend, PlainBackendClass)
 
 
 def test_pick_backend_plain_is_orthogonal_to_no_history() -> None:
     """Plain mode has no history file anyway, but setting both must
     still return PlainBackend (no conflict, no error)."""
-    backend = pick_backend(plain=True, no_history=True)
+    backend = pick_backend(backend="plain", no_history=True)
     assert isinstance(backend, PlainBackendClass)
 
 
-def test_pick_backend_plain_false_keeps_default_cascade(monkeypatch: pytest.MonkeyPatch) -> None:
-    """`plain=False` (the default) must NOT short-circuit; cascade as
+def test_pick_backend_auto_keeps_default_cascade(monkeypatch: pytest.MonkeyPatch) -> None:
+    """`backend="auto"` (the default) must NOT short-circuit; cascade as
     before."""
     pytest.importorskip("readline")
     _block_module(monkeypatch, "robotcode.repl._input._prompt_toolkit")
-    backend = pick_backend(plain=False)
+    backend = pick_backend(backend="auto")
     assert type(backend).__name__ == "ReadlineBackend"
 
 
+def test_pick_backend_explicit_readline_returns_readline_even_with_prompt_toolkit() -> None:
+    """Core feature: `backend="readline"` must ignore prompt_toolkit
+    even when it's installed. Lets devs (and users) exercise the
+    readline code path without uninstalling the prompt_toolkit extra."""
+    pytest.importorskip("readline")
+    pytest.importorskip("prompt_toolkit")
+    backend = pick_backend(backend="readline")
+    assert type(backend).__name__ == "ReadlineBackend"
+
+
+def test_pick_backend_explicit_prompt_toolkit_returns_prompt_toolkit() -> None:
+    pytest.importorskip("prompt_toolkit")
+    backend = pick_backend(backend="prompt-toolkit")
+    assert type(backend).__name__ == "PromptToolkitBackend"
+
+
+def test_pick_backend_explicit_readline_raises_when_unavailable(monkeypatch: pytest.MonkeyPatch) -> None:
+    """An explicit request for an uninstalled backend is a hard error —
+    silent fallback would defeat the purpose of the flag."""
+    from robotcode.repl._input import BackendUnavailableError
+
+    _block_module(monkeypatch, "robotcode.repl._input._readline")
+    with pytest.raises(BackendUnavailableError, match="readline backend not available"):
+        pick_backend(backend="readline")
+
+
+def test_pick_backend_explicit_prompt_toolkit_raises_when_unavailable(monkeypatch: pytest.MonkeyPatch) -> None:
+    from robotcode.repl._input import BackendUnavailableError
+
+    _block_module(monkeypatch, "robotcode.repl._input._prompt_toolkit")
+    with pytest.raises(BackendUnavailableError, match="prompt_toolkit backend requested"):
+        pick_backend(backend="prompt-toolkit")
+
+
+def test_pick_backend_unknown_value_raises() -> None:
+    """Defense in depth: the CLI uses `click.Choice` to filter values,
+    but a direct API caller could still pass garbage. Surface it loudly."""
+    with pytest.raises(ValueError, match="Unknown backend"):
+        pick_backend(backend="xyz")
+
+
 # ---------------------------------------------------------------------------
 # History-protocol methods (InputBackend.get_history / clear / delete)
 # ---------------------------------------------------------------------------