UserAdminModule

A PowerShell function management framework that gives any administrator a superpower in their own shell.

---

The Problem

Dot-sourcing loose .ps1 files is painful. Maintaining individual module manifests (.psd1) for every function you write is tedious. And when you have hundreds of functions spread across different domains, keeping track of them is nearly impossible.

UserAdminModule solves this with a simple folder-based organisation system backed by an interactive menu, a one-command scaffold tool, and a dynamic function index — with no hardcoded lists and no manifest maintenance required.

---

How It Works

UserAdminModule/               ← module root (published to PSGallery)
├── UserAdminModule.psd1       ← module manifest
├── UserAdminModule.psm1       ← root module (loads Public/, Private/, Shell/)
├── Public/                    ← exported base framework functions
│   ├── Import-PersonalModules.ps1
│   ├── Initialize-UserAdminModule.ps1
│   ├── Invoke-FunctionIndexRegeneration.ps1
│   ├── Invoke-PersonalModulesMenu.ps1
│   └── New-PSM1Module.ps1
├── Private/                   ← internal helpers (not exported)
│   └── Get-UserAdminModuleConfig.ps1
├── Shell/                     ← bundled UX submodule (loaded with -Global)
│   ├── Shell.psm1
│   └── Public/
├── profiles/                  ← profile scripts for users to dot-source
├── resources/                 ← config templates and data files
├── build/                     ← excluded from PSGallery package
└── .github/                   ← excluded from PSGallery package

Your own submodule library lives separately (configured via Initialize-UserAdminModule):

MyModules/
└── HomeLabTools/              ← your category (a submodule)
    ├── HomeLabTools.psm1      ← auto-generated by New-PSM1Module
    └── Public/
        ├── Get-ServerStatus.ps1
        └── Set-DnsRecord.ps1

1. Scaffold a submodule with New-PSM1Module — creates the full Public/Private/Classes/Configuration/Resources structure
2. Drop your .ps1 files into Public/
3. Import with Import-PersonalModules -Category HomeLabTools — tab-completion discovers your category automatically
4. Browse all categories interactively with Invoke-PersonalModulesMenu

No hardcoded category lists. No .psd1 maintenance per function. Works on any machine.

---

Prerequisites

Requirement	Minimum Version	Notes
PowerShell	5.1	7+ recommended
PSMenu	Any	Auto-installed from PSGallery

---

Installation

From PowerShell Gallery (Recommended)

# Install the module
Install-Module UserAdminModule -Scope CurrentUser

# Option A — Minimal setup (Import-Module only)
Initialize-UserAdminModule -Path 'C:\MyModules' -UpdateProfile

# Option B — Full shell UX (admin prompt, greeting, PSReadLine — PS edition auto-detected)
Initialize-UserAdminModule -Path 'C:\MyModules' -UpdateProfile -UseSharedProfile

Initialize-UserAdminModule will:

• Create C:\MyModules if it doesn't exist
• Write a line to your $PROFILE (with a .bak backup first):
  • Option A: Import-Module UserAdminModule -ErrorAction SilentlyContinue
  • Option B: dot-sources the bundled SharedPowershellProfile.ps1 (PS 7+) or SharedWindowsPowershellProfile.ps1 (PS 5.1) — chosen automatically
• Store the path in $env:APPDATA\UserAdminModule\config.json

Open a new PowerShell session — the module loads automatically.

From Source (Repo Clone)

git clone https://github.com/BanterBoy/UserAdminModule.git C:\UserAdminModule

Add to your $PROFILE:

# PowerShell 7+ (pwsh)
. 'C:\UserAdminModule\profiles\SharedPowershellProfile.ps1'

# Windows PowerShell 5.1
. 'C:\UserAdminModule\profiles\SharedWindowsPowershellProfile.ps1'

---

Quick Start

# 1 — Scaffold your first submodule
New-PSM1Module -folderPath 'C:\MyModules\HomeLabTools'

# 2 — Add a function (drop a .ps1 into Public/)
@'
function Get-ServerStatus {
    [CmdletBinding()]
    param([string]$ComputerName = $env:COMPUTERNAME)
    Get-Service -ComputerName $ComputerName | Where-Object { $_.Status -eq 'Running' }
}
'@ | Set-Content 'C:\MyModules\HomeLabTools\Public\Get-ServerStatus.ps1'

# 3 — Import your new category (tab-completes automatically)
Import-PersonalModules -Category HomeLabTools

# 4 — Use your function
Get-ServerStatus -ComputerName 'MyServer'

---

Interactive Menu

# Open the interactive multi-select menu (requires PSMenu)
Invoke-PersonalModulesMenu

# With category descriptions
Invoke-PersonalModulesMenu -ShowDescriptions

Use Space to select/deselect, Enter to confirm, Ctrl+C to cancel.

---

Submodule Structure

Each submodule created by New-PSM1Module follows this layout:

MyCategory/
├── MyCategory.psm1       (auto-generated — dot-sources Public/ and Private/)
├── Public/               (exported functions — become available after import)
│   └── Get-MyFunction.ps1
├── Private/              (internal helpers — not exported)
├── Classes/              (PowerShell classes)
├── Configuration/        (config files, JSON settings)
└── Resources/            (data files, templates, CSVs)

The .psm1 uses trap for error handling and exports only the Public/ basenames automatically.

---

Shared Profiles

The profiles/ folder contains full shell environment profiles that add the admin prompt indicator, console sizing, PSReadLine history prediction, and the F1 help key.

PowerShell 7+ — add to $PROFILE:

. "$($(Get-Module UserAdminModule -ListAvailable | Select-Object -First 1).ModuleBase)\profiles\SharedPowershellProfile.ps1"

Windows PowerShell 5.1 — add to $PROFILE:

. "$($(Get-Module UserAdminModule -ListAvailable | Select-Object -First 1).ModuleBase)\profiles\SharedWindowsPowershellProfile.ps1"

Or run Initialize-UserAdminModule -UpdateProfile -UseSharedProfile — it automatically picks the right shared profile for your PS edition and writes the dot-source line for you.

---

Base Framework Commands

Command	Alias	Description
Initialize-UserAdminModule	—	First-run setup — configures custom path, writes $PROFILE
Import-PersonalModules	—	Dynamic category import with tab-completion
Invoke-PersonalModulesMenu	—	Interactive PSMenu multi-select for batch import
New-PSM1Module	—	Scaffolds a new submodule folder structure
Invoke-FunctionIndexRegeneration	—	Rebuilds FunctionIndex.json and FunctionIndex.md

The bundled Shell submodule adds 16 UX functions including:

Function	Description
Set-PromptisAdmin	Colours the prompt red/green based on admin status
Set-TitleisAdmin	Sets the console window title with username, privilege level, and current path
Show-IsAdminOrNot	Writes whether the current session is running as administrator
Set-ConsoleConfig	Sets console window and buffer dimensions
Get-ConsoleConfig	Retrieves the current console window and buffer sizes
New-Greeting	Displays a random day-of-week greeting (PowerShell 7+ / Core only)
Restart-Profile	Reloads $PROFILE without restarting the shell
Open-ModuleMenuApp	Opens the HTML function reference in the browser (omma alias)
Install-ModuleIfNotPresent	Idempotent module installer
Install-RequiredModules	Installs and imports a defined set of required modules
Invoke-UserAdminModuleRequiredModules	Installs, updates, or removes UserAdminModule submodule dependencies
Get-LocationStack	Displays the current location stack
Set-Home	Changes location to drive root and stores the previous location
Restore-Location	Returns to the previously stored location
Initialize-Module	Installs and imports a module from PSGallery
IsAdmin (Test-IsAdmin)	Tests whether the current session has administrator privileges

---

Regenerating the Function Index

After adding new functions, rebuild the index:

# Auto-discovers built-in Shell submodule + your custom modules path from config
Invoke-FunctionIndexRegeneration -Verbose

# Scan specific paths only (overrides auto-discovery; accepts multiple paths)
Invoke-FunctionIndexRegeneration -ModulePath 'C:\MyModules', 'C:\MoreModules' -OutputPath 'C:\MyModules'

When called with no arguments, Invoke-FunctionIndexRegeneration reads your config.json (written by Initialize-UserAdminModule) to find the custom modules path and scans both that path and the built-in module root automatically. The output files (FunctionIndex.json and FunctionIndex.md) are written to the module root.

---

Configuration

The module config is stored at $env:APPDATA\UserAdminModule\config.json:

{
  "CustomModulesPath": "C:\\MyModules",
  "ConfigVersion": "1.0"
}

To reconfigure the custom path:

Initialize-UserAdminModule -Path 'D:\NewLocation'

---

License

MIT — see LICENSE