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 (current release is a preview)
Install-Module UserAdminModule -AllowPrerelease -Scope CurrentUser

# One-time setup — tell the module where your custom submodules will live
Initialize-UserAdminModule -Path 'C:\MyModules' -UpdateProfile

Initialize-UserAdminModule will:

• Create C:\MyModules if it doesn't exist
• Write Import-Module UserAdminModule to your $PROFILE (with a .bak backup first)
• 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 simply run Initialize-UserAdminModule -UpdateProfile for the minimal auto-setup (adds Import-Module UserAdminModule to $PROFILE).

---

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-DisplayIsAdmin	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

---

Publishing to PowerShell Gallery

These instructions apply to this module and to any module you build using the same framework.

Step 1 — Create a PowerShell Gallery Account

Sign in at powershellgallery.com using your Microsoft account.

Step 2 — Create an API Key

1. Click your username (top-right) → API Keys

2. Click Create

3. Fill in the form:

   Field	Value
   Key Name	e.g. UserAdminModule-Publish
   Expires In	365 days (or shorter for tighter security)
   Scopes → Push	✅ Select Push new packages and package versions
   Select Packages	Enter UserAdminModule in the Glob Pattern field

4. Click Create

5. Copy the key immediately — it is only displayed once. Store it in a password manager.

Step 3 — Publish Locally

cd C:\UserAdminModule

# Publish (live)
.\build\Publish-ToGallery.ps1 -ApiKey 'oy2abc...'

# Dry run — shows what would happen without uploading
.\build\Publish-ToGallery.ps1 -ApiKey 'oy2abc...' -WhatIf

# With verbose output
.\build\Publish-ToGallery.ps1 -ApiKey 'oy2abc...' -Verbose

Step 4 — Publish via GitHub Actions (Automated)

Store your API key as a GitHub repository secret so publishing can run automatically on every release tag.

1. Go to your GitHub repository → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Set Name to PSGALLERY_API_KEY and Value to your API key
4. Click Add secret

Push a version tag to trigger the workflow:

git tag v1.0.0-preview1
git push origin v1.0.0-preview1

The workflow (.github/workflows/publish-psgallery.yml) validates the manifest, then publishes automatically.

Updating the Version

Edit UserAdminModule.psd1 before each release:

# Pre-release
ModuleVersion = '1.0.0'
# In PrivateData.PSData:
Prerelease    = 'preview2'    # users install with -AllowPrerelease

# Stable release — remove the Prerelease line entirely
ModuleVersion = '1.0.0'

Important: Update ProjectUri in the manifest to point to your own GitHub repository (not BanterBoy/RDGScripts).

Setting Up the GitHub Repository

When creating your own GitHub repository for this module:

1. Create a new repository named UserAdminModule on GitHub
2. Update UserAdminModule.psd1:
   • ProjectUri → https://github.com/YourName/UserAdminModule
   • LicenseUri → https://github.com/YourName/UserAdminModule/blob/main/LICENSE
3. Add the PSGALLERY_API_KEY secret (Step 4 above)

---

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