Repository files navigation

Developer's Toolbox •Philosophy •Installation •Documentation •Tutorials •Hello World •Projects using cmd2 •

cmd2 is a tool for building interactive command line applications in Python. Its goal is to make itquick and easy for developers to build feature-rich and user-friendly interactive command lineapplications. It provides a simple API which is an extension of Python's built-incmd module. cmd2 provides a wealth of features on topof cmd to make your life easier and eliminates much of the boilerplate code which would be necessarywhen using cmd.

⚠️cmd2 is now "feature complete" for the2.x branch and is actively working on the3.0.0 release on themain branch. New features will only be addressed in 3.x moving forwards. Ifneed be, we will still fix bugs in 2.x.

When creating solutions developers have no shortage of tools to create rich and smart userinterfaces. System administrators have long been duct taping together brittle workflows based on amenagerie of simple command line tools created by strangers on github and the guy down the hall.Unfortunately, when CLIs become significantly complex the ease of command discoverability tends tofade quickly. On the other hand, Web and traditional desktop GUIs are first in class when it comesto easily discovering functionality. The price we pay for beautifully colored displays is complexityrequired to aggregate disperate applications into larger systems.cmd2 fills the niche betweenhighease of command discovery applications and smartworkflow automation systems.

Thecmd2 framework provides a great mixture of both worlds. Application designers can easilycreate complex applications and rely on the cmd2 library to offer effortless user facing help andextensive tab completion. When users become comfortable with functionality, cmd2 turns into afeature rich library enabling a smooth transition to full automation. If designed with enoughforethought, a well implemented cmd2 application can serve as a boutique workflow tool.cmd2 pullsoff this flexibility based on two pillars of philosophy:

• Tab Completion
• Automation Transition

Deep extensive tab completion and help text generation based on the argparse library create thefirst pillar of 'ease of command discovery'. The following is a list of features in this category.

• Great tab completion of commands, subcommands, file system paths, and shell commands.
• Custom tab completion for user designed commands via simple function overloading.
• Tab completion frompersistent_history_file sources added with very little friction.
• Automatic tab completion ofargparse flags and optional arguments.
• Path completion easily enabled.
• When all else fails, custom tab completion based onchoices_provider can fill any gaps.

cmd2 creates the second pillar of 'ease of transition to automation' through alias/macro creation,command line argument parsing and execution of cmd2 scripting.

• Flexible alias and macro creation for quick abstraction of commands.
• Text file scripting of your application withrun_script (@) and_relative_run_script (@@)
• Powerful and flexible built-in Python scripting of your application using therun_pyscriptcommand
• Transcripts for use with built-in regression can be automatically generated fromhistory -t orrun_script -t

On all operating systems, the latest stable version ofcmd2 can be installed using pip:

pip install -U cmd2

cmd2 works with Python 3.9+ on Windows, macOS, and Linux. It is pure Python code with few 3rd-partydependencies. It works with both conventional CPython and free-threaded variants.

For information on other installation options, seeInstallation Instructions in thecmd2 documentation.

The latest documentation for cmd2 can be read online here:https://cmd2.readthedocs.io/en/latest/

It is available in HTML, PDF, and ePub formats.

The best way to learn the cmd2 api is to delve into the example applications located in source underexamples.

• PyOhio 2019 presentation:
  • video
  • slides
  • example code
• 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
• cmd2 example applications
  • Basic cmd2 examples to demonstrate how to use various features
• Advanced Examples
  • More complex examples that demonstrate more featuers about how to put together a completeapplication

#!/usr/bin/env python"""A simple cmd2 application."""importcmd2classFirstApp(cmd2.Cmd):"""A simple cmd2 application."""defdo_hello_world(self,_:cmd2.Statement):self.poutput('Hello World')if__name__=='__main__':importsysc=FirstApp()sys.exit(c.cmdloop())

If you think you've found a bug, please first read through the openIssues. If you're confident it's a new bug, go aheadand create a new GitHub issue. Be sure to include as much information as possible so we canreproduce the bug. At a minimum, please state the following:

• cmd2 version
• 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

Possibly defunct but still good examples

Note: If you have created an application based oncmd2 that you would like us to mention here,please get in touch.