228 lines
6.3 KiB
ReStructuredText
228 lines
6.3 KiB
ReStructuredText
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
|
|
|