PSToolkit is an interactive PowerShell script that streamlines common help desk diagnostics and maintenance activities on Windows workstations. The script guides operators through targeted menus for network checks, system triage, performance monitoring, and basic remediation steps while recording a full activity log and optional JSON exports for later review.
The repository currently ships as a single script (PSToolkit.ps1) with no external module dependencies. This audit focuses on improving documentation, quality guardrails, and repository hygiene without modifying the functional code paths.
- Interactive console menus for network diagnostics, system health inspection, performance snapshots, and maintenance operations.
- Automatic session logging to
Outputs/Logswith timestamps for traceability. - Optional JSON exports under
Outputs/Jsonfor structured reporting and downstream analysis. - Administrator check (
Ensure-Administrator) to prevent privileged actions from running without elevation. - Modular helper functions (
Log-Action,Write-JsonOutput,Get-ValidatedChoice) that centralize reusable behavior within the script.
- Windows PowerShell 5.1 or PowerShell 7.0+ on Windows.
- Local administrative rights for maintenance actions such as restarting services, clearing temporary files, and launching Disk Cleanup.
- Sufficient disk space on the host for log and JSON export directories created at runtime.
- Clone the repository
git clone https://github.com/your-org/PSToolkit.git cd PSToolkit
- Review execution policy (if not already permitting local scripts)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
- Verify PowerShell version
$PSVersionTable.PSVersion
Restore your organization’s preferred execution policy after confirming PSToolkit runs as expected.
- Launch PowerShell with administrative rights when you intend to run maintenance tasks.
- Navigate to the cloned repository directory.
- Execute the script:
.\PSToolkit.ps1
- Follow the on-screen prompts to select diagnostic or maintenance actions. Logs and JSON exports are created automatically.
Select a support option:
1. Network Diagnostics
2. System Diagnostics
3. Performance Monitoring
4. Maintenance Tools
5. Exit
Enter your choice (1-5): 1
- Logs:
Outputs/Logs/SupportLog_<timestamp>.txt - JSON exports:
Outputs/Json/*.json
| Issue | Resolution |
|---|---|
| Execution policy prevents script launch | Run the installation step above to set RemoteSigned, then retry. |
| Log files fail to write | Confirm the current user has write access to the repository directory or set PowerShell to run as Administrator. |
| Maintenance actions warn about privileges | Rerun PowerShell as Administrator; the script exits early without elevation. |
| Windows Update check warning appears | Install the optional PSWindowsUpdate module or skip the menu item. |
For additional support or to report issues, open a ticket in the repository issue tracker with log excerpts and the selected menu path.
- The codebase currently consists of a single script. Future refactors should consider extracting reusable logic into a PowerShell module to improve testability.
- Repository automation now includes linting guidance via GitHub Actions (see
.github/workflows/lint.yml). - Planned test coverage will use Pester. Place future tests under the
tests/directory. - Run static analysis locally with
Invoke-ScriptAnalyzer -Path .after installingPSScriptAnalyzer.
While automated tests are not yet implemented, contributors can prepare the environment with the following commands:
Install-Module -Name PSScriptAnalyzer -Scope CurrentUser -Force
Invoke-ScriptAnalyzer -Path .\PSToolkit.ps1Add Pester tests as they are developed:
Invoke-Pester -Path .\tests -Output Detailed- Input prompts for ping targets and defragmentation accept raw user input. Validate entries manually before confirming operations.
- Clearing temporary files and launching Disk Cleanup or defragmentation may affect end-user workloads; communicate scheduled maintenance windows.
- Recommended security tooling: PSScriptAnalyzer for linting, secret scanning via GitHub Advanced Security (if available), and Just Enough Administration (JEA) policies for production environments.
A high-level view of repository contents is maintained in docs/DEPENDENCY_OVERVIEW.md. Update this document when new modules, scripts, or documentation directories are added.
This project is licensed under the MIT License.
Created and maintained by Daniel Madden. Contributions are welcome via pull requests that include updated documentation and lint results.