Language / Idioma: ๐บ๐ธ English | ๐ง๐ท Portuguรชs (Brasil)
IT Toolbox CLI (it-toolbox) is a cross-platform, interactive terminal utility (TUI/CLI) built with PHP 8.3+, Laravel Zero, and Laravel Prompts. Designed for IT Support Technicians, Help Desk Engineers, and System Administrators, it unifies daily troubleshooting, hardware/OS diagnostics, print spooler recovery, network health checks, and safe temporary file cleanup across both Windows and Linux (distribution-agnostic) environments from a single portable binary.
- ๐ฉบ Full Machine Health Check & Score (
health:check):- Calculates an objective 0โ100 Health Score across RAM usage, disk storage, internet/DNS connectivity, print queue state, and critical OS logs, classifying the workstation into Healthy (
80โ100), Warning (50โ79), or Critical (0โ49) with visual progress bar, checklist (โ/โ ๏ธ/โ), and actionable remediation recommendations.
- Calculates an objective 0โ100 Health Score across RAM usage, disk storage, internet/DNS connectivity, print queue state, and critical OS logs, classifying the workstation into Healthy (
- ๐ฅ System & Hardware Diagnostics (
system):- Inspect OS metadata, kernel version, architecture, hostname, and system uptime.
- Real-time CPU model, core/thread count, load percentage, and physical RAM usage.
- Storage volume capacity, used/free space, and usage percentages across NTFS/ext4/btrfs/xfs filesystems.
- Top resource-consuming processes viewer with interactive frozen process termination (
PIDkill). - Critical OS Logs & Recent Errors (
system:logs): Inspect critical and error events recorded in the last 24 hours (Get-WinEventon Windows /journalctl -p err&/var/log/syslogon Linux).
- ๐จ Printers & Spooler Management (
printer):- List installed printers, driver details, ports/URIs, default status, and queue states (
PowerShell Get-Printeron Windows /CUPS lpstaton Linux). - One-step print queue purge and spooler service restart (
net stop/start spooler&PRINTERScleanup on Windows /cancel -a&systemctl restart cupson Linux).
- List installed printers, driver details, ports/URIs, default status, and queue states (
- ๐ Network & Connectivity Diagnostics (
network):- Active network interface inspection (
IPv4,IPv6,MAC, link status). - Automated connectivity health check (Default Gateway ping, external ICMP latency to
8.8.8.8/1.1.1.1, and DNS resolution verification). - One-click DNS cache flush and DHCP IP lease renewal.
- Active listening
TCP/UDPports and owning processes scanner (Get-NetTCPConnection/ss -tulnp).
- Active network interface inspection (
- ๐งน System Maintenance & Cleanup (
maintenance):- Safe cleanup of user and system temporary directories (
%TEMP%,C:\Windows\Temp,/tmp,/var/tmp,~/.cache/thumbnails), gracefully skipping locked/in-use files and reporting freed disk space.
- Safe cleanup of user and system temporary directories (
- ๐ Diagnostic Reports & Export (
report):- Export complete hardware, OS, printer, and network diagnostic snapshots to structured
.mdand.jsonfiles for ticketing systems and audit logs.
- Export complete hardware, OS, printer, and network diagnostic snapshots to structured
- โฌ๏ธ Over-the-Air Self-Update (
self:update):- Automatically queries GitHub Releases for newer versions and atomically updates the running standalone binary (
.exe, Linux ELF, or.phar) in-place.
- Automatically queries GitHub Releases for newer versions and atomically updates the running standalone binary (
- ๐ Native Bilingual Interface (
i18n):- Full support for English (
en) and Brazilian Portuguese (pt_BR), selectable via--lang=flag or dynamically inside the interactive numeric TUI menu.
- Full support for English (
The project strictly separates presentation (TUI commands), orchestration, and operating-system-specific execution using the Adapter/Driver Pattern and Factory Pattern. All external OS commands are executed safely through Symfony\Component\Process\Process using argument arrays to prevent Command Injection.
flowchart TD
User(["IT Technician / SysAdmin"]) --> CLI["CLI Entrypoint (it-toolbox)"]
CLI --> Menu["ToolboxMenuCommand / Subcommands (Laravel Prompts)"]
Menu --> I18n["Translator Service (lang/en & lang/pt_BR)"]
Menu --> Factory["SystemDriverFactory::make(PHP_OS_FAMILY)"]
Factory -->|Windows| WinDriver["WindowsDriver (SystemDriverInterface)"]
Factory -->|Linux| LinDriver["LinuxDriver (SystemDriverInterface)"]
WinDriver --> WinProcess["Symfony Process (Argument Arrays)"]
LinDriver --> LinProcess["Symfony Process / Native Filesystem"]
WinProcess --> WinAPI["PowerShell CIM / WMI / net / ipconfig / taskkill"]
LinProcess --> LinAPI["/proc / POSIX / CUPS (lpstat/cancel) / ip / ss / resolvectl"]
WinAPI --> DTO["ActionResult Readonly DTO"]
LinAPI --> DTO
DTO --> Menu
Choose the installation method that best fits your scenario:
Ideal for field IT technicians and target workstations. Download the self-contained native executable (powered by static-php-cli micro.sfx) directly from the GitHub Releases page and run it immediately without installing PHP or Composer:
Windows (x64):
# Download 'it-toolbox-windows-x64.exe' from GitHub Releases and run:
.\it-toolbox-windows-x64.exe
# Or launch directly in your preferred language:
.\it-toolbox-windows-x64.exe --lang=en
.\it-toolbox-windows-x64.exe --lang=pt_BRLinux (x64):
# Download 'it-toolbox-linux-x64' from GitHub Releases, grant execution permission, and run:
chmod +x it-toolbox-linux-x64
./it-toolbox-linux-x64
# (Optional) Install globally in PATH:
sudo mv it-toolbox-linux-x64 /usr/local/bin/it-toolbox
it-toolboxIf your machine already has PHP 8.3+ installed, download the cross-platform it-toolbox PHAR archive from GitHub Releases:
php it-toolboxFor developers who want to customize the source code or run the automated test suite:
# 1. Clone the repository
git clone https://github.com/Dev-lib4n/it-toolbox-cli.git
cd it-toolbox-cli
# 2. Install dependencies via Composer
composer installNote: Administrator privileges (Windows) or
sudo(Linux) are recommended for privileged system operations (spooler restart, system temp cleanup, and DHCP renewal).
Launch the interactive dashboard. If --lang is omitted, an interactive language selector is presented on startup:
# Launch with interactive language selector
php it-toolbox
# Launch directly in English
php it-toolbox --lang=en
# Launch directly in Brazilian Portuguese
php it-toolbox --lang=pt_BREvery module can also be executed directly in headless/CLI scripts or terminal sessions:
| Command | Module | Description | Options |
|---|---|---|---|
php it-toolbox menu |
Core TUI | Launch the interactive numeric TUI main menu (default command) | --lang=en|pt_BR, --once |
php it-toolbox health:check |
Health | Run a full machine health audit with a 0โ100 score and recommendations | --export, --lang=en|pt_BR |
php it-toolbox system:info |
System | Display OS, CPU, RAM, and disk health metrics | --lang=en|pt_BR |
php it-toolbox system:top |
System | List top processes by resource usage and optionally kill a PID | --limit=10, --lang=en|pt_BR |
php it-toolbox system:logs |
System | Inspect critical and error OS log events from the last 24 hours | --limit=15, --lang=en|pt_BR |
php it-toolbox printer:list |
Printers | List installed printers, drivers, ports, and status | --lang=en|pt_BR |
php it-toolbox printer:clear |
Printers | Restart print spooler / CUPS and purge stuck print jobs | --force, --lang=en|pt_BR |
php it-toolbox network:check |
Network | Inspect network interfaces and run ping/DNS health checks | --lang=en|pt_BR |
php it-toolbox network:flush |
Network | Flush DNS resolver cache and renew DHCP lease | --force, --lang=en|pt_BR |
php it-toolbox network:ports |
Network | List active listening TCP/UDP ports and owning processes | --lang=en|pt_BR |
php it-toolbox clean:temp |
Maintenance | Safely purge temporary files and report freed space | --force, --lang=en|pt_BR |
php it-toolbox report:export |
Reports | Export full system diagnostic report to .md and/or .json |
--format=md|json|both, --output=DIR, --lang=en|pt_BR |
php it-toolbox self:update |
Core CLI | Check GitHub Releases and self-update the running executable | --check, --lang=en|pt_BR |
Compile the application into a portable .phar (builds/it-toolbox) or bundle it with static-php-cli (micro.sfx) into zero-dependency native executables (builds/it-toolbox-linux-x64 and builds/it-toolbox-windows-x64.exe):
# Build portable PHAR only
php it-toolbox app:build it-toolbox --build-version=1.0.0
# Build PHAR + Native Linux & Windows x64 standalone binaries
./scripts/build-standalone.sh 1.0.0The test suite is powered by Pest PHP and mocks OS-level processes so all tests run deterministically on both Windows and Linux CI runners:
# Run all Unit and Feature tests
./vendor/bin/pest
# Check code style with Laravel Pint
./vendor/bin/pint --test- Language & Runtime: PHP 8.3+ (
declare(strict_types=1), typed properties,matchexpressions,readonlyclasses) - Micro-Framework: Laravel Zero
- Terminal UI (TUI): Laravel Prompts (
select,table,spin,confirm,info,warning,error) - Process Execution:
Symfony\Component\Process\Process(strictly array-based arguments for Command Injection prevention) - Internationalization:
Illuminate\Translation(lang/en&lang/pt_BR) - Architectural Patterns:
- Adapter / Driver Pattern:
SystemDriverInterfaceimplemented byWindowsDriverandLinuxDriver. - Factory Pattern:
SystemDriverFactorydynamically resolves the driver viaPHP_OS_FAMILY. - Data Transfer Objects (DTO): Immutable
readonly class ActionResultfor standardized operation outcomes.
- Adapter / Driver Pattern:
- Testing & QA: Pest PHP, Mockery, Laravel Pint, and GitHub Actions CI across Ubuntu and Windows runners.
This project is open-sourced software licensed under the MIT License. Copyright (c) 2026 Ian Carlos Pinheiro Libanio da Silva.