final changes (#1200)

Readme facelift from PR #1200 

5 files changed, 196 insertions, 297 deletions

diff --git a/.github/images/graph.drawio.png b/.github/images/graph.drawio.png
new file mode 100644
index 00000000..ecc33ce9
--- /dev/null
+++ b/.github/images/graph.drawio.png
diff --git a/.gitignore b/.gitignore
index e8c68ee9..1fdfc6a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,3 +37,6 @@ Pipfile.lock
 
 # Virtualenv directory
 .venv
+
+# Commitizen configuration
+.cz.toml
\ No newline at end of file
diff --git a/README.md b/README.md
index 12b7c78e..edc2ea76 100755
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-cmd2: a tool for building interactive command line apps
-=======================================================
+<h1 align="center">cmd2 : immersive interactive command line applications</h1>
+
 [![Latest Version](https://img.shields.io/pypi/v/cmd2.svg?style=flat-square&label=latest%20stable%20version)](https://pypi.python.org/pypi/cmd2/)
 [![GitHub Actions](https://github.com/python-cmd2/cmd2/workflows/CI/badge.svg)](https://github.com/python-cmd2/cmd2/actions?query=workflow%3ACI)
 [![Azure Build status](https://python-cmd2.visualstudio.com/cmd2/_apis/build/status/python-cmd2.cmd2?branch=master)](https://python-cmd2.visualstudio.com/cmd2/_build/latest?definitionId=1&branch=master)
@@ -7,6 +7,17 @@ cmd2: a tool for building interactive command line apps
 [![Documentation Status](https://readthedocs.org/projects/cmd2/badge/?version=latest)](http://cmd2.readthedocs.io/en/latest/?badge=latest)
 <a href="https://discord.gg/RpVG6tk"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Chat"></a>
 
+
+<p align="center">
+  <a href="#main-features">Main Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#tutorials">Tutorials</a> •
+  <a href="#projects-using-cmd2">Projects using cmd2</a> •
+  <a href="#version-two-notes">Version 2.0 Notes</a>
+</p>
+
+[![Screenshot](cmd2.png)](https://youtu.be/DDU_JH6cFsA)
+
 cmd2 is a tool for building interactive command line applications in Python. Its goal is to make it
 quick and easy for developers to build feature-rich and user-friendly interactive command line
 applications.  It provides a simple API which is an extension of Python's built-in
@@ -14,49 +25,50 @@ applications.  It provides a simple API which is an extension of Python's built-
 of cmd to make your life easier and eliminates much of the boilerplate code which would be necessary
 when using cmd.
 
-Click on image below to watch a short video demonstrating the capabilities of cmd2:
-[![Screenshot](cmd2.png)](https://youtu.be/DDU_JH6cFsA)
+The developers toolbox
+----------------------
+
+![system schema](https://github.com/python-cmd2/cmd2/blob/README_facelift/.github/images/graph.drawio.png)
+
+
+When creating solutions developers have no shortage of tools to create rich and smart user interfaces. 
+System administrators have long been duct taping together brittle workflows based on a menagerie 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 to fade quickly. 
+On the other hand, Web and traditional desktop GUIs are first in class when it comes to easily discovering functionality. 
+The price we pay for beautifully colored displays is complexity required to aggregate disperate applications into larger systems.
+`cmd2` fills the niche between high [ease of command discovery](https://clig.dev/#ease-of-discovery) applications and smart workflow automation systems. 
 
-Main Features
+The `cmd2` framework provides a great mixture of both worlds. Application designers can easily create complex applications and rely on the cmd2 library to offer effortless user facing help and extensive tab completion. 
+When users become comfortable with functionality, cmd2 turns into a feature rich library enabling a smooth transition to full automation. If designed with enough forethought, a well implemented cmd2 application can serve as a boutique workflow tool. `cmd2` pulls off this flexibility based on two pillars of philosophy:
+
+* Tab Completion
+* Automation Transition
+
+Philosophy
 -------------
-- Searchable command history (`history` command and `<Ctrl>+r`) - optionally persistent
+
+<a href="https://imgflip.com/i/63h03x"><img src="https://i.imgflip.com/63h03x.jpg" title="made at imgflip.com" width="70%" height="%70"/></a>
+
+
+Deep extensive tab completion and help text generation based on the argparse library create the first 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 from `persistent_history_file` sources added with very little friction.
+- Automatic tab completion of `argparse` flags and optional arguments.
+- Path completion easily enabled.
+- When all else fails, custom tab completion based on `choices_provider` can fill any gaps.
+
+<a href="https://imgflip.com/i/66t0y0"><img src="https://i.imgflip.com/66t0y0.jpg" title="made at imgflip.com" width="70%" height="70%"/></a>
+
+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 with `run_script` (`@`) and `_relative_run_script` (`@@`)
-- Python scripting of your application with ``run_pyscript``
-- Run shell commands with ``!``
-- Pipe command output to shell commands with `|`
-- Redirect command output to file with `>`, `>>`
-- Bare `>`, `>>` with no filename send output to paste buffer (clipboard)
-- Optional `py` command runs interactive Python console which can be used to debug your application
-- Optional `ipy` command runs interactive IPython console which can be used to debug your application
-- Option to display long output using a pager with ``cmd2.Cmd.ppaged()``
-- Multi-line commands
-- Special-character command shortcuts (beyond cmd's `?` and `!`)
-- Command aliasing similar to bash `alias` command
-- Macros, which are similar to aliases, but they can contain argument placeholders
-- Ability to run commands at startup from an initialization script
-- Settable environment parameters
-- Parsing commands with arguments using `argparse`, including support for subcommands
-- Unicode character support
-- Good tab completion of commands, subcommands, file system paths, and shell commands
-- Automatic tab completion of `argparse` flags when using one of the `cmd2` `argparse` decorators
-- Support for Python 3.6+ on Windows, macOS, and Linux
-- Trivial to provide built-in help for all commands
-- Built-in regression testing framework for your applications (transcript-based testing)
+- Powerful and flexible built-in Python scripting of your application using the `run_pyscript` command
 - Transcripts for use with built-in regression can be automatically generated from `history -t` or `run_script -t`
-- Alerts that seamlessly print while user enters text at prompt
-- Colored and stylized output using `ansi.style()`
-
-Version 2.0 Notes
------------------
-- Python 3.5 support ended
-  - The last release of `cmd2` to support Python 3.5 was the 1.5.0 release on January 31, 2021.  Python 3.5 was
-    [released](https://docs.python.org/3/whatsnew/3.5.html) on Sept. 13, 2015 and it reached
-    [end-of-life](https://devguide.python.org/#status-of-python-branches) on September 5, 2020.
-- `cmd2` 2.0 simplifies portions of the API and introduces new features. Many of these changes are not compatible with
-  previous versions of `cmd2`. For assistance with porting your current `cmd2` application to version 2.0, see the
-  [CHANGELOG](https://github.com/python-cmd2/cmd2/blob/master/CHANGELOG.md) for a description of each breaking
-  change and enhancement.
-    
+
+
 Installation
 ------------
 On all operating systems, the latest stable version of `cmd2` can be installed using pip:
@@ -79,135 +91,7 @@ The latest documentation for cmd2 can be read online here: https://cmd2.readthed
 It is available in HTML, PDF, and ePub formats.
 
 
-Feature Overview
-----------------
-Instructions for implementing each feature follow.
-
-- Extension of the `cmd` module. So capabilities provided by `cmd` still exist
-    - Your applicaiton inherits from `cmd2.Cmd`, let's say you call this class `MyApp`
-    ```Python
-    import cmd2
-    class MyApp(cmd2.Cmd):
-      pass
-    ```
-    - Define a command named **foo** by creating a method named **do_foo**
-    ```Python
-    class MyApp(cmd2.Cmd):
-        def do_foo(self, args):
-            """This docstring is the built-in help for the foo command."""
-            self.poutput(cmd2.style('foo bar baz', fg=cmd2.Fg.RED))
-    ```
-    - By default the docstring for your **do_foo** method is the help for the **foo** command
-        - NOTE: This doesn't apply if you use one of the `argparse` decorators mentioned below
-    - Can provide more custom help by creating a **help_foo** method (except when using `argparse` decorators)
-    - Can provide custom tab completion for the **foo** command by creating a **complete_foo** method
-    - Easy to upgrade an existing `cmd` app to `cmd2`
-    - Run your `cmd2` app using the built-in REPL by executing the **cmdloop** method
-
-- Searchable command history
-    - Readline history using `<Ctrl>+r`, arrow keys, and other [Readline Shortcut keys](http://readline.kablamo.org/emacs.html)
-    - `cmd2` `history` command provides flexible and powerful search
-        - If you wish to exclude some of your custom commands from the history, append their names to the list at `Cmd.exclude_from_history`.
-        - Do `help history` in any `cmd2` application for more information
-    - Both of the above types of history can be optionally persistent between application runs
-        - Via optional `persistent_history_file` argument to `cmd2.Cmd` initializer
-
-- Simple scripting using text files with one command + arguments per line
-    - See the [Command Scripts](https://cmd2.readthedocs.io/en/latest/features/scripting.html#command-scripts) section of the `cmd2` docs for more info
-    - See [script.txt](https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/script.txt) for a trivial example script that can be
-    used in any `cmd2` application with the `run_script` command (or `@` shortcut)
-
-- Powerful and flexible built-in Python scripting of your application using the `run_pyscript` command
-    - Run arbitrary Python scripts within your `cmd2` application with the ability to also call custom `cmd2` commands
-    - No separate API for your end users to learn
-        - Syntax for calling `cmd2` commands in a `run_pyscript` is essentially identical to what they would enter on the command line
-    - See the [Python Scripts](https://cmd2.readthedocs.io/en/latest/features/scripting.html#python-scripts) section of the `cmd2` docs for more info
-    - Also see the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py) 
-    example in conjunction with the [conditional.py](https://github.com/python-cmd2/cmd2/blob/master/examples/scripts/conditional.py) script
-
-- Parsing commands with `argparse`
-    - The built-in `cmd2.with_argparser` decorator will parse arguments using `argparse.ArgumentParser`
-      - Optionally, `cmd2.with_argparser(.., with_unknown_args=True)` can be used to pass all unknown arguments as a list
-
-    ```Python
-    from cmd2 import Cmd2ArgumentParser, with_argparser
-
-    argparser = Cmd2ArgumentParser()
-    argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    argparser.add_argument('words', nargs='+', help='words to say')
-
-    @with_argparser(argparser)
-    def do_speak(self, args):
-        """Repeats what you tell me to."""
-        words = []
-        for word in args.words:
-            if args.piglatin:
-                word = '%s%say' % (word[1:], word[0])
-            if args.shout:
-                word = word.upper()
-            words.append(word)
-        self.stdout.write('{}\n'.format(' '.join(words)))
-    ```
-
-    See [Argument Processing](https://cmd2.readthedocs.io/en/latest/features/argument_processing.html) in the docs for more details
-    
-    NOTE: `cmd2` also provides the `Cmd2ArgumentParser` customization of `argparse.ArgumentParser` for prettier formatting
-    of help and error messages.
-
-- `cmd2` applications function like a full-featured shell in many ways (and are cross-platform)
-    - Run arbitrary shell commands by preceding them with `!` or `shell`
-    - Redirect the output of any command to a file with `>` for overwrite or `>>` for append
-        - If no file name provided after the `>`/`>>`, then output goes to the clipboard/pastebuffer
-    - Pipe the output of any command to an arbitrary shell command with `|`
-    - Create your own custom command aliases using the `alias` command
-    - Create your own custom macros using the `macro` command (similar to aliases, but allow arguments)
-    - Settable environment parameters that users can change during execution supported via `set` command
-    - Option to display long output using a pager with ``cmd2.Cmd.ppaged()``
-    - Optionally specify a startup script that end users can use to customize their environment
-
-- Top-notch tab completion capabilities which are easy to use but very powerful
-    - For a command **foo** implement a **complete_foo** method to provide custom tab completion for that command
-        - But the helper methods within `cmd2` discussed below mean you would rarely have to implement this from scratch
-    - Commands which use one of the `argparse` decorators have automatic tab completion of `argparse` flags
-        - And also provide help hints for values associated with these flags
-        - Experiment with the [argprint.py](https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py) example
-        using the **oprint** and **pprint** commands to get a feel for how this works
-    - `basic_complete` helper method for tab completion against a list
-    - `path_complete` helper method provides flexible tab completion of file system paths
-        - See the [paged_output.py](https://github.com/python-cmd2/cmd2/blob/master/examples/paged_output.py) example for a simple use case
-        - See the [python_scripting.py](https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py) example for a more full-featured use case
-    - `delimiter_complete` helper method for tab completion against a list but each match is split on a delimiter 
-        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use this feature
-    - `flag_based_complete` helper method for tab completion based on a particular flag preceding the token being completed
-    - `index_based_complete` helper method for tab completion based on a fixed position in the input string
-        - See the [basic_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/basic_completion.py) example for a demonstration of how to use these features
-        - `flag_based_complete()` and `index_based_complete()` are basic methods and should only be used if you are not
-        familiar with argparse. The recommended approach for tab completing positional tokens and flags is to use
-        argparse-based completion
-    - `cmd2` in combination with `argparse` also provide several advanced capabilities for automatic tab completion
-        - See the [argparse_completion.py](https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_completion.py) example for more info
-
-- Multi-line commands
-
-    Any command accepts multi-line input when its name is listed the `multiline_commands` optional argument to 
-    `cmd2.Cmd.__init`. The program will keep expecting input until a line ends with any of the characters listed in the 
-    `terminators` optional argument to `cmd2.Cmd.__init__()`  .  The default terminators are `;` and `\n` (empty newline).
-
-- Special-character shortcut commands (beyond cmd's "@" and "!")
-
-    To create a single-character shortcut for a command, update `Cmd.shortcuts`.
-
-- Asynchronous alerts based on events happening in background threads
-    - `cmd2` provides the following helper methods for providing information to users asynchronously even though the `cmd2`
-    REPL is a line-oriented command interpreter:
-        - `async_alert` - display an important message to the user while they are at the prompt in between commands
-            - To the user it appears as if an alert message is printed above the prompt
-        - `async_update_prompt` - update the prompt while the user is still typing at it
-            - This is good for alerting the user to system changes dynamically in between commands
-        - `set_window_title` - set the terminal window title
-            - This changes the window title of the terminal that the user is running the `cmd2` app within
-
+The best way to learn the cmd2 api is to delve into the example applications located in source under examples.
 
 Tutorials
 ---------
@@ -219,121 +103,30 @@ Tutorials
 * [Cookiecutter](https://github.com/cookiecutter/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
+* [Example Applications](https://github.com/jayrod/cmd2-example-apps)
 
-Example Application
--------------------
 
-Example cmd2 application (**examples/example.py**):
+Hello World
+-----------
 
 ```python
 #!/usr/bin/env python
-# coding=utf-8
-"""
-A sample application for cmd2.
-"""
-import random
-import sys
+"""A simple cmd2 application."""
 import cmd2
 
-class CmdLineApp(cmd2.Cmd):
-    """ Example cmd2 application. """
-
-    # Setting this true makes it run a shell command if a cmd2/cmd command doesn't exist
-    # default_to_shell = True
-    MUMBLES = ['like', '...', 'um', 'er', 'hmmm', 'ahh']
-    MUMBLE_FIRST = ['so', 'like', 'well']
-    MUMBLE_LAST = ['right?']
-
-    def __init__(self):
-        self.maxrepeats = 3
-        shortcuts = dict(cmd2.DEFAULT_SHORTCUTS)
-        shortcuts.update({'&': 'speak'})
-
-        super().__init__(multiline_commands=['orate'], shortcuts=shortcuts)
-
-        # Make maxrepeats settable at runtime
-        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
-
-    speak_parser = cmd2.Cmd2ArgumentParser()
-    speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    speak_parser.add_argument('words', nargs='+', help='words to say')
-
-    @cmd2.with_argparser(speak_parser)
-    def do_speak(self, args):
-        """Repeats what you tell me to."""
-        words = []
-        for word in args.words:
-            if args.piglatin:
-                word = '%s%say' % (word[1:], word[0])
-            if args.shout:
-                word = word.upper()
-            words.append(word)
-        repetitions = args.repeat or 1
-        for i in range(min(repetitions, self.maxrepeats)):
-            # .poutput handles newlines, and accommodates output redirection too
-            self.poutput(' '.join(words))
-
-    do_say = do_speak  # now "say" is a synonym for "speak"
-    do_orate = do_speak  # another synonym, but this one takes multi-line input
-
-    mumble_parser = cmd2.Cmd2ArgumentParser()
-    mumble_parser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
-    mumble_parser.add_argument('words', nargs='+', help='words to say')
-
-    @cmd2.with_argparser(mumble_parser)
-    def do_mumble(self, args):
-        """Mumbles what you tell me to."""
-        repetitions = args.repeat or 1
-        for i in range(min(repetitions, self.maxrepeats)):
-            output = []
-            if (random.random() < .33):
-                output.append(random.choice(self.MUMBLE_FIRST))
-            for word in args.words:
-                if (random.random() < .40):
-                    output.append(random.choice(self.MUMBLES))
-                output.append(word)
-            if (random.random() < .25):
-                output.append(random.choice(self.MUMBLE_LAST))
-            self.poutput(' '.join(output))
 
-if __name__ == '__main__':
-    app = CmdLineApp()
-    sys.exit(app.cmdloop())
-```
+class FirstApp(cmd2.Cmd):
+    """A simple cmd2 application."""
 
-The following is a sample session running example.py.
-Thanks to Cmd2's built-in transcript testing capability, it also serves as a test
-suite for example.py when saved as *transcript_regex.txt*.
-Running
+  def do_hello_world(self, _: cmd2.Statement):
+    self.poutput('Hello World')
 
-```bash
-python example.py -t transcript_regex.txt
-```
-will run all the commands in the transcript against `example.py`, verifying that the output produced
-matches the transcript.
-
-example/transcript_regex.txt:
-
-```text
-# Run this transcript with "python example.py -t transcript_regex.txt"
-# Anything between two forward slashes, /, is interpreted as a regular expression (regex).
-# The regex for editor will match whatever program you use.
-# regexes on prompts just make the trailing space obvious
-(Cmd) set
-allow_style: '/(Terminal|Always|Never)/'
-always_show_hint: False
-debug: False
-echo: False
-editor: /.*?/
-feedback_to_output: False
-maxrepeats: 3
-quiet: False
-timing: False
-```
+if __name__ == '__main__':
+    import sys
+    c = FirstApp()
+    sys.exit(c.cmdloop())
 
-Regular expressions can be used anywhere within a transcript file simply by enclosing them within forward slashes, `/`.
+```
 
 
 Found a bug?
@@ -348,30 +141,23 @@ If you think you've found a bug, please first read through the open [Issues](htt
 * Include any traceback or error message associated with the bug
 
 
-Open source projects using cmd2
+Projects using cmd2
 -------------------------------
 
-Here are a few examples of open-source projects which use `cmd2`:
+| Application Name                                                | Description                                                                                                                     |   |
+|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|---|
+| [Jok3r](http://www.jok3r-framework.com)                         | Network & Web Pentest Automation Framework                                                                                      |   |
+| [CephFS Shell](https://github.com/ceph/ceph)                    | [Ceph](https://ceph.com/) is a distributed object, block, and file storage platform                                             |   |
+| [psiTurk](https://psiturk.org)                                  | An open platform for science on Amazon Mechanical Turk                                                                          |   |
+| [Poseidon](https://github.com/CyberReboot/poseidon)             | Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques. |   |
+| [Unipacker](https://github.com/unipacker/unipacker)             | Automatic and platform-independent unpacker for Windows binaries based on emulation                                             |   |
+| [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager) | A command line tool and python library for managing a tomcat server                                                             |   |
+| [Expliot](https://gitlab.com/expliot_framework/expliot)         | Internet of Things (IoT) exploitation framework                                                                                 |   |
+| [mptcpanalyzer]()                                               | Tool to help analyze mptcp pcaps                                                                                                |   |
+| [clanvas](https://github.com/marklalor/clanvas)                 | Command-line client for Canvas by Instructure                                                                                   |   |
+
+
+Possibly defunct but still good examples
 
-* [Jok3r](http://www.jok3r-framework.com)
-    * Network & Web Pentest Automation Framework
-* [CephFS Shell](http://docs.ceph.com/docs/master/cephfs/cephfs-shell/)
-    * [Ceph](https://ceph.com/) is a distributed object, block, and file storage platform
 * [JSShell](https://github.com/Den1al/JSShell)
-    * An interactive multi-user web JavaScript shell
-* [psiTurk](https://psiturk.org)
-    * An open platform for science on Amazon Mechanical Turk
-* [Poseidon](https://github.com/CyberReboot/poseidon)
-    * Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques
-* [Unipacker](https://github.com/unipacker/unipacker)
-    * Automatic and platform-independent unpacker for Windows binaries based on emulation
-* [FLASHMINGO](https://github.com/fireeye/flashmingo)
-    * Automatic analysis of SWF files based on some heuristics. Extensible via plugins.
-* [tomcatmanager](https://github.com/tomcatmanager/tomcatmanager)
-    * A command line tool and python library for managing a tomcat server
-* [Expliot](https://gitlab.com/expliot_framework/expliot)
-    * Internet of Things (IoT) exploitation framework
-* [mptcpanalyzer](https://github.com/teto/mptcpanalyzer)
-    * Tool to help analyze mptcp pcaps
-* [clanvas](https://github.com/marklalor/clanvas)
-    * Command-line client for Canvas by Instructure
+* [FLASHMINGO](https://github.com/fireeye/flashmingo) 
diff --git a/readme_files/shout_out.csv b/readme_files/shout_out.csv
new file mode 100644
index 00000000..e298fd24
--- /dev/null
+++ b/readme_files/shout_out.csv
@@ -0,0 +1,14 @@
+Application Name, Description
+[Jok3r](http://www.jok3r-framework.com),Network & Web Pentest Automation Framework
+[CephFS Shell](https://github.com/ceph/ceph),'[Ceph](https://ceph.com/) is a distributed object, block, and file storage platform'
+[psiTurk](https://psiturk.org),An open platform for science on Amazon Mechanical Turk
+[Poseidon](https://github.com/CyberReboot/poseidon),Leverages software-defined networks (SDNs) to acquire and then feed network traffic to a number of machine learning techniques.
+[Unipacker](https://github.com/unipacker/unipacker),Automatic and platform-independent unpacker for Windows binaries based on emulation
+[tomcatmanager](https://github.com/tomcatmanager/tomcatmanager),A command line tool and python library for managing a tomcat server
+[Expliot](https://gitlab.com/expliot_framework/expliot),Internet of Things (IoT) exploitation framework
+[mptcpanalyzer](),Tool to help analyze mptcp pcaps
+[clanvas](https://github.com/marklalor/clanvas),Command-line client for Canvas by Instructure
+
+Oldies but goodie,,
+[JSShell](https://github.com/Den1al/JSShell),An interactive multi-user web JavaScript shell.
+[FLASHMINGO](https://github.com/fireeye/flashmingo),Automatic analysis of SWF files based on some heuristics. Extensible via plugins.
\ No newline at end of file
diff --git a/readme_files/shoutout.txt b/readme_files/shoutout.txt
new file mode 100644
index 00000000..362c3a7e
--- /dev/null
+++ b/readme_files/shoutout.txt
@@ -0,0 +1,96 @@
+Name: 
+Source Code:
+Status: 
+Description: 
+Genre: 
+
+
+
+Name: Microsoft/ Azure Counterfit
+Source Code: https://github.com/Azure/counterfit
+Status: Active
+Description: Counterfit is a command-line tool and generic automation layer for assessing the security of machine learning systems.
+Genre: Security
+
+Name: MQTT-Pwn 
+Source Code: https://github.com/akamai-threat-research/mqtt-pwn
+Status: Stale 
+Description: MQTT-PWN intends to be a one-stop-shop for IoT Broker penetration-testing and security assessment operations 
+Genre: Security
+
+Name: OpenBeacon2
+Source Code: https://github.com/etherkit/OpenBeacon2
+Description: Commandline tool for interfacing with hardware in the [OpenBeacon](https://www.openbeacon.org/) environment.
+Genre: Utility 
+
+Name: GreenWaves-Technologies/gap_sdk
+Source Code: https://github.com/GreenWaves-Technologies/gap_sdk
+Status: Active 
+Description: GAP SDK allows you to compile and execute applications on the GAP IoT Application Processor.  
+Genre: Utility, IoT
+
+Name: JSShell 
+Source Code: https://github.com/Den1al/JSShell
+Status: Unknown 
+Description: An interactive multi-user web based javascript shell. 
+Genre: Utility, Web 
+
+
+Name: pyOS 
+Source Code: https://github.com/muhrin/pyos
+Status: Active 
+Description: A fresh way to interact with your python objects as though they were files on your filesystem. 
+Genre: ????  
+
+Name: darkcode357/thg-framework 
+Source Code: https://github.com/darkcode357/thg-framework
+Status: Inactive
+Description: THG is a framework for security testing and ctf games, but it can be used as a library for exploit development.
+Genre: Security 
+
+
+Name: qsecure-labs/Overloard 
+Source Code: https://github.com/qsecure-labs/overlord
+Status: Active 
+Description: Overlord provides a python-based console CLI which is used to build Red Teaming infrastructure in an automated way.  
+Genre: Security 
+
+
+Name: seemoo-lab/internalblue 
+Source Code: https://github.com/seemoo-lab/internalblue
+Status: Active 
+Description:  Bluetooth experimentation framework for Broadcom and Cypress chips.
+Genre: utility 
+
+Name: icl-rocketry/Avionics
+Source Code: https://github.com/icl-rocketry/Avionics
+Status: Active 
+Description: The main repository for hardware and software assosciated with the Ricardo Avionics Ecosystem.
+Genre: Utility 
+
+
+Name: jonny1102/nmap-parse
+Source Code: https://github.com/jonny1102/nmap-parse
+Status: Inactive 
+Description: Command line nmap XML parser 
+Genre: Security 
+
+Name: cybiere/baboossh
+Source Code: https://github.com/cybiere/baboossh
+Status: Active
+Description:SSH spreading made easy for red teams in a hurry 
+Genre: Security 
+
+Name: qilingframework/qiling
+Source Code: https://github.com/qilingframework/qiling
+Status: Active 
+Description: Qiling Advanced Binary Emulation Framework
+Genre: Security 
+
+
+Name: JohnHammond/katana
+Source Code: https://github.com/JohnHammond/katana
+Status: Active 
+Description: Katana - Automatic CTF Challenge Solver in Python3
+Genre: Security 
+