GNU OpenVBS Framework 🚀
A powerful Python toolkit for generating and executing VBScript (.vbs) files with ease.
OpenVBS bridges the gap between Python’s simplicity and VBScript’s Windows automation capabilities, allowing you to create sophisticated Windows automation scripts using intuitive Python functions and an intuitive CLI.
NOTE: The examples may be outdated,or broken due to frequevent updates and continuosly-changing ecosystem!
✨ Features
🔧 Core Language Features
- Variables, constants, and arrays
- Control flow (if/else, loops, select/case)
- Functions and subroutines
- Error handling and debugging
- Object creation and manipulation
📁 File System Operations
- File and folder management
- Text file reading/writing
- Directory traversal and organization
- Path manipulation utilities
🌐 Windows Integration
- Registry operations (read/write)
- Environment variables
- Shell command execution
- Windows Management Instrumentation (WMI)
- System information gathering
📊 Data Processing
- String manipulation and formatting
- Mathematical operations
- Date/time functions
- Array and collection handling
🌐 Network & Communication
- HTTP GET/POST requests
- File downloading
- Email sending (via CDO)
- Web service interactions
🎛️ User Interface
- Message boxes and input dialogs
- File/folder picker dialogs
- System notifications
- Custom dialog creation
📦 Advanced Features
- Module system for code reuse
- Configuration management
- Performance profiling
- Diacnostics
- Plugins!
🚀 Quick Start
Installation
# Clone the repository
git clone https://github.com/yourusername/openvbs.git
cd openvbs
# Install dependencies (optional)
pip install colorama # For enhanced CLI colors
Basic Example
from openvbs import *
# Clear any previous script
clear_vbs()
# Create variables
define_variable("username", "John Doe")
define_variable("age", 25)
# Show a message
message_prompt(f"Hello {username}!", title="Welcome")
# Create a simple loop
for_loop("i", 1, 5, 1, 'WScript.Echo "Count: " & i')
# Execute the generated VBScript
execute_vbs()
File Operations Example
from openvbs import *
clear_vbs()
# Create a log file
create_file("system.log", "System started at: ")
write_file("system.log", current_datetime(), append=True)
# Read system information
get_system_info()
# Organize files by extension
template_file_organizer()
execute_vbs()
Windows Automation Example
from openvbs import *
clear_vbs()
# Read from registry
registry_read("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion", "ProductName")
# Get environment variables
define_variable("user_profile", "")
user_profile = get_env_var("USERPROFILE")
# Run a system command
shell_execute("notepad.exe", wait_on_return=False)
execute_vbs()
📚 Documentation
Core Functions
Variables and Constants
define_variable("name", "value") # Create a variable
const_variable("PI", 3.14159) # Create a constant
define_array("numbers", [1, 2, 3, 4]) # Create an array
Control Flow
# Conditional statements
if_else("x > 10", "WScript.Echo 'Large'", "WScript.Echo 'Small'")
# Loops
for_loop("i", 1, 10, 1, "WScript.Echo i")
do_while("x < 100", "x = x + 1")
# Select case
select_case("userChoice", {
1: "WScript.Echo 'Option 1'",
2: "WScript.Echo 'Option 2'",
"default": "WScript.Echo 'Invalid choice'"
})
File Operations
file_system_object() # Initialize file system
create_file("data.txt", "Hello World") # Create file with content
read_file("data.txt") # Read file content
write_file("log.txt", "Entry", True) # Write/append to file
delete_file("temp.txt") # Delete file
folder_exists("C:\MyFolder") # Check folder existence
Windows Integration
# Registry operations
registry_read("HKCU\Software\MyApp", "Setting1")
registry_write("HKCU\Software\MyApp", "Setting1", "NewValue")
# Environment variables
get_env_var("USERNAME")
set_env_var("MY_VAR", "MyValue")
# Shell commands
shell_execute("dir", window_style=1, wait_on_return=True)
run_program("C:\Program Files\MyApp\app.exe", "/silent")
Network Operations
# HTTP requests
http_get("https://api.example.com/data")
http_post("https://api.example.com/submit", "data=value")
download_file("https://example.com/file.zip", "C:\Downloads\file.zip")
# Email
send_email("user@example.com", "Subject", "Message body", "smtp.server.com")
🛠️ Advanced Features
Module System
# Export current script as a module
export("my_utilities.vbs")
# Import a module into current script
get("my_utilities.vbs")
# Clear all saved modules
clear_modules()
Configuration Management
# Save settings
set_setting("default_path", "C:\MyApp")
set_setting("auto_backup", True)
# Load settings
path = get_setting("default_path", "C:\Default")
backup_enabled = get_setting("auto_backup", False)
Debugging and Profiling
# Debug output
debug_print("Variable x = " + str(x))
# Log to file
log_to_file("Process started", "app.log")
# Performance timing
start_timer("processing")
# ... your code here ...
end_timer("processing")
# Assertions
assert_condition("x > 0", "X must be positive")
Error Handling
# Try-catch style error handling
error_handling(
try_block="risky_operation()",
catch_block="WScript.Echo 'Operation failed: ' & Err.Description"
)
# Traditional VBS error handling
on_error_resume_next()
# ... code that might fail ...
on_error_goto_zero()
Plugins!
To use use plugins folow these steps:
- Take your plugin file and paste it to files/plugins(or inside PMN, run the command plugin install ).
- Run cli.bat.
- Run plugin load.
- Run plugin list(for seeing your plugins).
- Run plugin include.
📁 Project Structure
openvbs/
├── openvbs/
│ ├── __init__.py # Main imports and exports
│ ├── main.py # Core functions and language features
│ ├── runner.py # VBScript execution engine
├── files/
│ ├── windows/
│ │ └── output.vbs # Generated VBScript output
│ ├── compiled_output/ # Packaged executables
│ ├── modules/ # Saved script modules
├── src/
│ └── examples/ # Example scripts
├── tests/ # Unit tests
└── LICENSE # License file
🎯 Use Cases
System Administration
- Automated system monitoring and reporting
- User account management
- Software deployment and configuration
- Registry maintenance and cleanup
File Management
- Bulk file operations and organization
- Automated backups and synchronization
- Log file processing and analysis
- Data migration and conversion
Network Operations
- Automated data collection from web services
- Batch downloading and processing
- Email automation and notifications
- System health monitoring
Windows Automation
- Application control and automation
- Scheduled task creation and management
- System configuration deployment
- Performance monitoring and alerting
🚨 Requirements
- Windows Operating System (Windows 7/10/11)
- Python 3.6+
- Windows Script Host (pre-installed on Windows)
- IExpress (for .exe packaging, included with Windows)
Optional Dependencies
pip install colorama # Enhanced terminal colors
🤝 Contributing
Contributions are welcome! Here’s how to get started:
- Fork the repository
-
Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests
-
Commit your changes:
git commit -m 'Add amazing feature'
-
Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
Development Setup
# Clone your fork
git clone https://github.com/yourusername/openvbs.git
cd openvbs
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venvScriptsactivate
# Install development dependencies
pip install -r requirements-dev.txt
# Run tests
python -m pytest tests/
📋 Examples
Example 1: System Information Script
from openvbs import *
clear_vbs()
comment("System Information Gatherer")
# Get computer name
get_env_var("COMPUTERNAME")
define_variable("computer_name", get_env_var("COMPUTERNAME"))
# Get OS information
get_os_info()
# Get system specs
get_system_info()
# Save to file
write_file("system_info.txt", "System Report Generated: ")
write_file("system_info.txt", current_datetime(), append=True)
execute_vbs()
Example 2: File Backup Script
from openvbs import *
clear_vbs()
comment("Automated Backup Script")
# Define source and destination
define_variable("source_folder", "C:\Important Files")
define_variable("backup_folder", "D:\Backups")
# Create backup folder with timestamp
define_variable("timestamp", "")
current_datetime()
# Format: YYYY-MM-DD_HH-MM-SS
string_replace(current_datetime(), "/", "-")
string_replace(current_datetime(), ":", "-")
string_replace(current_datetime(), " ", "_")
# Copy files
shell_execute('xcopy "' + source_folder + '" "' + backup_folder + '\Backup_' + timestamp + '\" /E /I /Y')
message_prompt("Backup completed successfully!", title="Backup Status")
execute_vbs()
Example 3: Network Monitor
from openvbs import *
clear_vbs()
comment("Network Connectivity Monitor")
# Test multiple servers
servers = ["google.com", "github.com", "stackoverflow.com"]
for server in servers:
define_variable(f"result_{server.replace('.', '_')}", "")
shell_execute(f'ping -n 1 {server} > nul')
if_else(
"Err.Number = 0",
f'WScript.Echo "{server}: Online"',
f'WScript.Echo "{server}: Offline"'
)
# Log results
log_to_file("Network check completed", "network_monitor.log")
execute_vbs()
🐛 Troubleshooting
Common Issues
Q: „cscript.exe not found“ error
A: Ensure you’re running on Windows with Windows Script Host installed. Try running cscript
in Command Prompt to verify.
Q: VBScript execution fails with syntax error
A: Check the generated output.vbs
file for syntax issues. Use debug_print()
to trace execution.
Q: File permission errors
A: Run your Python script as Administrator, or ensure the target directories are writable.
📜 License
This project is licensed under the GNU GENERAL PUBLIC LICENSE V3 – see the LICENSE file for details.
🏆 Acknowledgments
- Inspired by the need for simpler Windows automation
- Built for system administrators, developers, and automation enthusiasts
- Thanks to the Python and VBScript communities for inspiration
🔮 Roadmap
Upcoming Features
- [ ] GUI Builder: Visual interface for creating VBScript GUIs
- [ ] PowerShell Integration: Hybrid PowerShell/VBScript generation
- [ ] Active Directory Integration: User and computer management functions
- [ ] Database Connectivity: SQL Server and Access database operations
- [ ] Excel Automation: Advanced Excel manipulation capabilities
- [ ] Service Management: Windows service creation and management
- [ ] Event Log Integration: Reading and writing Windows event logs
- [ ] Scheduled Task API: Advanced task scheduler integration
Version History
- v2.0 Patch – Removed packaging due to high risk of system instability and sudden reboots
- v2.0 – Major rewrite with enhanced CLI, templates, and packaging
- v1.0 – Initial release with basic VBScript generation