---
id: click-shell
version: "2.1"
license: BSD
license_treatment: permissive
maintenance: active
---

# click-shell — An extension to click that easily turns your click app into a shell utility

License: permissive · Maintenance: active · Downloads: 101.3K/mo

## What it is and what it does

click-shell is a decorator that wraps click command groups to provide an interactive shell interface instead of a one-shot CLI. When you run your app with no arguments, it enters a persistent shell prompt where users can type commands repeatedly; if arguments are passed, it behaves like a normal click app. The shell includes command completion built on Python's cmd module, adapted to work with click's command structure.

The package is designed for developers who want to turn existing click applications into interactive utilities with minimal code changes—typically just swapping the @click.group decorator for @click_shell.shell. It's useful when you want users to run multiple commands in a session without restarting the process each time.

Use it for:

- Convert a CLI tool into an interactive shell so users can run multiple commands without restarting.
- Add command completion to a click app for better user experience in shell mode.
- Build a REPL-like interface for administrative or utility tools built with click.
- Create an interactive application shell for data processing or system management tasks.
- Provide both one-shot CLI and interactive shell modes from the same click command group.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts a click command-line app into an interactive shell with command completion by replacing @click.group with @click_shell.shell.

Yes, if you have a click app and want to add interactive shell mode with minimal effort. The package is stable, has low install friction, and is actively maintained. The main caveat is that the last release was in 2021—verify compatibility with your Python version before relying on it for new projects.

## Install

pip install click-shell
uv add click-shell
poetry add click-shell

## Installing click-shell

Before you install: Low friction: single runtime dependency (click) and a pure-Python wheel. Maintenance is active with recent commits, though the last release was in 2021.

License in practice: BSD license is permissive; you can use, modify, and distribute this package with minimal restrictions.

Quickstart:

from click_shell import shell

@shell(prompt='my-app > ', intro='Starting my app...')
def my_app():
    pass

@my_app.command()
def testcommand():
    print('testcommand is running')

if __name__ == '__main__':
    my_app()

Verify before relying:

- Whether command completion works across all supported Python versions (2.7, 3.6–3.9 listed in classifiers).
- Current compatibility with modern Python 3.10+ versions, given the latest release was in 2021.

## Package facts

- License: BSD (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 101.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

interactive shell for click apps, click command completion, turn cli into shell, click shell decorator, command-line shell wrapper, interactive repl for click, shell mode for click commands, cli-framework, interactive-shell, repl

[View on SkillFed](https://skillfed.io/packages/click-shell) · [View on PyPI](https://pypi.org/project/click-shell/)