click-repl

click-repl turns any Click-based CLI into an interactive shell: calling register_repl(cli) registers a repl subcommand that drops the user into a prompt where subsequent commands run against the same parent Click context — so state stored on ctx.obj (caches, open connections, config) persists between invocations instead of being rebuilt on every process start.

Built on python-prompt-toolkit, it provides tab-completion of subcommands and options, in-session command history, a !-prefix for running raw shell commands, and a built-in :help command. For finer control than the one-line register_repl helper, applications can call the lower-level repl() function directly and pass custom prompt_kwargs (e.g. a FileHistory for persistent history across sessions) to the underlying PromptSession.

What You Get

• register_repl() - a one-line helper that adds a repl subcommand to an existing click.Group
• The lower-level repl() function for custom REPL commands with configurable prompt_kwargs
• Tab-completion for subcommands and options via python-prompt-toolkit
• Persistent parent context (ctx.obj) across REPL invocations, avoiding repeated expensive setup
• A !-prefix for executing raw shell commands and a built-in :help command inside the REPL

Common Use Cases

• Adding an interactive shell mode to a Click-based CLI tool for exploratory or repeated command usage
• Avoiding repeated expensive startup work (DB connections, config loading) by keeping the Click context alive across commands
• Providing tab-completion and command history for CLI tools used interactively by developers or operators
• Building nested REPL experiences for complex multi-group CLI applications

Under The Hood

Architecture - click_repl centers on a ReplContext class (in core.py) that tracks a stack of nested REPL sessions via _ctx_stack.py, reusing the click Context object across commands entered in the prompt loop implemented in _repl.py; a custom _completer.py module implements python-prompt-toolkit’s Completer interface by introspecting the active Click group’s registered commands and options to drive tab-completion. Tech Stack - Python with click and prompt-toolkit as core runtime dependencies, plus typing_extensions for ParamSpec/TypeAlias backports, fully type-annotated with a py.typed marker for downstream type checking. Code Quality - 18 test files cover the completer, REPL context stack, and core command loop; the codebase uses from __future__ import annotations and modern typing constructs consistently across all modules. API Design - The common path is a single call, register_repl(cli), added after defining a normal Click group; power users drop to the lower-level repl() function with a prompt_kwargs dict for PromptSession customization (e.g., persistent history files), keeping the everyday API to one line while still exposing prompt-toolkit’s full configuration surface when needed.