cli-tool/readme.rst

Advanced CLI Framework with Prompt Toolkit
============================================

.. 

    1. Clear feature overview with emoji icons
    2. Installation instructions
    3. Basic usage example
    4. Command reference table
    5. Detailed advanced usage scenarios
    6. Customization guide for extending functionality
    7. Example session demonstrating key features
    8. Troubleshooting section
    9. License and contribution information



A feature-rich Python command-line interface framework inspired by cmd2 but built on prompt_toolkit with:

- Full color support
- Command history search
- Script execution capability
- Nested command support
- Session logging
- Command history saving

.. contents:: This README provides comprehensive documentation for your advanced CLI framework, including:
   :depth: 1
   :numbered:


Features
--------

- 🎨 **Color Support**: Custom color scheme for commands, errors, and information
- 🔍 **History Search**: Press ``Ctrl+R`` to search through command history
- 📜 **Script Execution**: Run batch commands from files
- 🔗 **Nested Commands**: Execute multiple commands separated by semicolons
- 📝 **Session Logging**: Record entire sessions to files
- 💾 **History Saving**: Export command history to files
- 💻 **System Commands**: Execute shell commands directly
- 🚦 **Error Handling**: Colored error messages with details
- 🤖 **Smart Autocompletion**: Context-aware suggestions for commands and arguments

Installation
------------

.. code-block:: bash

    pip install prompt_toolkit pygments

Basic Usage
-----------

.. code-block:: bash

    python advanced_cli.py

Key Commands
------------
+---------------+-------------------------------------------------------+
| Command       | Description                                           |
+===============+=======================================================+
| help          | Show help for commands                                |
+---------------+-------------------------------------------------------+
| echo          | Echo back the input                                   |
+---------------+-------------------------------------------------------+
| exit          | Exit the application                                  |
+---------------+-------------------------------------------------------+
| ls            | List directory contents (with color)                  |
+---------------+-------------------------------------------------------+
| run_script    | Execute commands from a script file                   |
+---------------+-------------------------------------------------------+
| log_start     | Start session logging (optional filename argument)    |
+---------------+-------------------------------------------------------+
| log_stop      | Stop session logging                                  |
+---------------+-------------------------------------------------------+
| save_history  | Save command history to file                          |
+---------------+-------------------------------------------------------+
| system        | Execute a system shell command                        |
+---------------+-------------------------------------------------------+

Advanced Usage
--------------

1. **Colorized Output**:
   The CLI automatically colorizes different types of messages:
   - Commands: Green
   - Errors: Red
   - Information: Blue
   - Success messages: Bright Green
   - Directories in listings: Blue

2. **Nested Commands**:
   Execute multiple commands in one line by separating them with semicolons:
   
   .. code-block:: text
   
        >>> echo Hello; echo World; ls

3. **Script Execution**:
   Create a script file (e.g., ``commands.txt``):
   
   .. code-block:: text
   
        # My command script
        echo Running script
        ls
        system date
   
   Then execute it:
   
   .. code-block:: text
   
        >>> run_script commands.txt

4. **Session Logging**:
   
   .. code-block:: text
   
        # Start logging to a file
        >>> log_start session.log  
        
        # Execute commands...
        >>> echo This is being logged
        >>> ls
        
        # Stop logging
        >>> log_stop

5. **History Management**:
   
   .. code-block:: text
   
        # Save command history to file
        >>> save_history my_history.txt

6. **System Commands**:
   
   .. code-block:: text
   
        # Execute any system command
        >>> system ls -l
        >>> system python --version

Customization
-------------
1. **Add New Commands**:
   Create methods starting with ``do_`` in the CLI class:
   
   .. code-block:: python
   
        def do_mycommand(self, arg):
            """Description of mycommand"""
            print(f"Executed with: {arg}")

2. **Custom Argument Completion**:
   Implement argument completers for your commands:
   
   .. code-block:: python
   
        def argcompleter_mycommand(self, arg):
            return ["option1", "option2", "option3"]

3. **Modify Colors**:
   Edit the style dictionary in the ``__init__`` method:
   
   .. code-block:: python
   
        custom_style = Style.from_dict({
            'prompt': 'ansicyan bold',
            'command': 'ansigreen',
            'error': 'ansired bold',
            # ... other styles ...
        })

Example Session
---------------
.. code-block:: text

    Welcome to Advanced CLI (Type 'help' for commands)
    >>> log_start session.log
    Logging started to session.log
    
    >>> ls; system date
    file1.txt
    file2.py
    docs/
    Tue Jun 19 15:30:45 CEST 2025
    
    >>> run_script commands.txt
    Executing: echo Running script
    Echo: Running script
    Executing: ls
    file1.txt
    file2.py
    docs/
    Executing: system date
    Tue Jun 19 15:31:22 CEST 2025
    Script 'commands.txt' executed successfully
    
    >>> save_history
    History saved to command_history.txt
    
    >>> exit
    Goodbye!

Troubleshooting
---------------

- **Command not recognized**: Ensure your method starts with ``do_`` prefix
- **Autocompletion not working**: Implement ``argcompleter_<command>`` method
- **Logging errors**: Check file write permissions

License
-------

MIT License - Free for personal and commercial use

Contributing
------------

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request