Quick start • Why cmd2? • Installation • Documentation • Projects using cmd2
cmd2 makes it quick to build powerful, polished command-line applications and REPLs in Python.
Start with a subclass of the standard library's
cmd.Cmd, then add commands while cmd2 handles the
details that make an application pleasant to build and use: argument parsing, generated help, tab
completion, command history, scripting, output styling, and much more.
You can use cmd2 for a small internal tool and grow the same application into an extensible,
scriptable interface without replacing the framework or writing the usual CLI boilerplate.
Install cmd2:
pip install cmd2Then create app.py:
from typing import Annotated
import cmd2
from cmd2.annotated import Argument, Option
class App(cmd2.Cmd):
"""A small interactive application."""
@cmd2.with_annotated
def do_greet(
self,
name: Annotated[str, Argument(help_text="person to greet")],
count: Annotated[int, Option(help_text="number of greetings")] = 1,
) -> None:
"""Greet a person."""
for _ in range(count):
self.poutput(f"Hello, {name}!")
if __name__ == "__main__":
App().cmdloop()cmd2 supports Typer-style syntax for specifying command arguments
with type annotations. In this example, @cmd2.with_annotated turns name and count into a
positional argument and an option.
Run it with python app.py. Your new greet command already has input validation, generated help,
and tab completion for its options. The application also includes discoverable help, command
history, aliases, macros, scripting, shell integration, and other built-in commands.
(Cmd) help greet
Usage: greet [-h] [--count COUNT] name
(Cmd) greet --count 2 Ada
Hello, Ada!
Hello, Ada!
See the getting started tutorial to build a more complete application.
- Define commands as Python methods and use familiar
argparseparsers for arguments and subcommands. A single parser definition drives validation, help, and completion. - Render Rich tables and other styled objects, with consistent helpers for normal output, errors, warnings, and paging.
- Organize large applications into independently testable and dynamically loadable CommandSets, and customize the command lifecycle with hooks.
- Integrate existing Python code, shell tools, or asynchronous work instead of restructuring your application around the framework.
- Run on Windows, macOS, and Linux with a pure-Python package and a small dependency footprint.
- Tab completion: provide context-aware completion for commands, subcommands, options, choices, file paths, and custom data sources, with descriptive hints for completion candidates. Learn more about completion.
- History: search, edit, rerun, save, and optionally persist previously entered commands. Users also get familiar navigation and reverse search such as Ctrl+R. Learn more about history.
- Unicode: accept Unicode in commands, arguments, file names, and output, and run UTF-8 command scripts for applications used in any language. Learn more about command scripts.
- Shell shortcuts and hotkeys: use familiar Readline-style keyboard shortcuts for navigating and
editing the command line, including Emacs-style bindings provided by
prompt-toolkit. Learn more about keyboard shortcuts. - Help: generate discoverable, categorized help for commands, subcommands, and arguments directly from their argument parsers. Learn more about help.
- Rich UI/UX: offer syntax highlighting, Fish-style history suggestions, multiline input, configurable prompts, completion menus, themes, and an optional bottom toolbar. Learn more about prompts and toolbars and themes.
- Shell scripting: automate the same commands users run interactively by passing them as command arguments or standard input from shell scripts. Learn more about automating cmd2 applications.
- Python scripting: run Python scripts inside the application for loops, branching, complex control flow, and integration with the application's commands and data. Learn more about Python scripts.
- Run shell commands: execute operating-system commands without leaving the application, using
the built-in
shellcommand or its!shortcut. Learn more about OS integration. - Redirect output: send command output to files or the clipboard, or pipe it through one or more shell commands. Learn more about output redirection and pipes.
- Aliases, macros, and shortcuts: let users customize names, parameterized commands, and terse shortcuts for repetitive workflows without changing the application. Learn more about aliases, macros, and shortcuts.
- Startup scripts: initialize an application consistently by running saved commands every time it starts. Learn more about startup commands and scripts.
- Embedded Python and IPython shells: drop into an interactive Python or IPython session for experimentation, debugging, object introspection, and access to application state. Learn more about embedded Python shells.
- Color, style, and tables: produce readable output with Rich colors and styles, custom themes, paging, and flexible table layouts. Learn more about generating output and creating tables.
On all operating systems, the latest stable version of cmd2 can be installed using pip:
pip install -U cmd2cmd2 works with Python 3.11+ on Windows, macOS, and Linux. It is pure Python code with few 3rd-party dependencies. It works with both conventional CPython and free-threaded variants.
For information on other installation options, see Installation Instructions in the cmd2 documentation.
Important
Upgrading from an older release? Versions 3.x and 4.x include significant backwards-incompatible changes. Review the changelog and migration guide before upgrading.
Read the latest documentation online or download it in
HTML, PDF, and ePub formats. The
examples directory contains focused,
runnable demonstrations of individual features.
- cmd2 example applications
- Basic cmd2 examples to demonstrate how to use various features
- Advanced Examples
- More complex examples that demonstrate more features about how to put together a complete application
- Cookiecutter Templates from community
- Basic cookiecutter template for cmd2 application : https://github.com/jayrod/cookiecutter-python-cmd2
- Advanced cookiecutter template with external plugin support : https://github.com/jayrod/cookiecutter-python-cmd2-ext-plug
If you think you've found a bug, please first read through the open Issues. If you're confident it's a new bug, go ahead and create a new GitHub issue. Be sure to include as much information as possible so we can reproduce the bug. At a minimum, please state the following:
cmd2version- Python version
- OS name and version
- What you did to cause the bug to occur
- Include any traceback or error message associated with the bug
| Application Name | Description | Organization or Author |
|---|---|---|
| CephFS Shell | The Ceph File System, or CephFS, is a POSIX-compliant file system built on top of Ceph’s distributed object store | ceph |
| garak | LLM vulnerability scanner that checks if an LLM can be made to fail in a way we don't want | NVIDIA |
| Argus | The Ultimate Information Gathering Toolkit | JASON13 |
| medusa | Binary instrumentation framework that that automates processes for the dynamic analysis of Android and iOS Applications | Ch0pin |
| InternalBlue | Bluetooth experimentation framework for Broadcom and Cypress chips | Secure Mobile Networking Lab |
| SCCMHunter | A post-ex tool built to streamline identifying, profiling, and attacking SCCM related assets in an Active Directory domain | Garret Foster |
| Unipacker | Automatic and platform-independent unpacker for Windows binaries based on emulation | unipacker |
| Frankenstein | Broadcom and Cypress firmware emulation for fuzzing and further full-stack debugging | Secure Mobile Networking Lab |
| Poseidon | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques. | Faucet SDN |
| DFTimewolf | A framework for orchestrating forensic collection, processing and data export | log2timeline |
| LazyOwn | The first RedTeam/APT Framework with an AI-powered C&C, featuring rootkits to conceal campaigns, undetectable malleable implants | Grisuno |
| GAP SDK | SDK for Greenwaves Technologies' GAP8 IoT Application Processor | GreenWaves Technologies |
| REW Sploit | Emulate and Dissect Metasploit Framework (MSF) and other attacks | REW-sploit |
| tomcatmanager | A command line tool and python library for managing a tomcat server | tomcatmanager |
| Falcon Toolkit | Unleash the power of the CrowdStrike Falcon Platform at the CLI | CrowdStrike |
| EXPLIoT | Internet of Things Security Testing and Exploitation framework | expliot_framework |
| Pobshell | A Bash‑like shell for live Python objects: cd, ls, cat, find and CLI piping for object code, str values & more |
Peter Dalloz |
Possibly defunct but still good examples
| Application Name | Description | Organization or Author |
|---|---|---|
| Katana | Automatic CTF Challenge Solver | John Hammond |
| SatanSword (in Chinese) | Comprehensive Penetration Framework for Red Teaming | Lucifer1993 |
| Jok3r | Network & Web Pentest Automation Framework | Koutto |
| Counterfit | a CLI that provides a generic automation layer for assessing the security of ML models | Microsoft Azure |
| Overlord | Red Teaming Infrastructure Automation | QSecure Labs |
| Automated Reconnaissance Pipeline | An automated target reconnaissance pipeline | epi052 |
| JSShell | An interactive multi-user web JavaScript (JS) shell | Den1al |
| RedShell | An interactive command prompt for red teaming and pentesting | Verizon |
| FLASHMINGO | Automatic analysis of SWF files based on some heuristics. Extensible via plugins. | Mandiant |
| psiTurk | An open platform for science on Amazon Mechanical Turk | NYU Computation and Cognition Lab |
Note: If you have created an application based on cmd2 that you would like us to mention here,
please get in touch.