⚡ PowerShell Command Builder

Status: ✅ Live (v3)
URL: aguidetocloud.com/ps-builder/
Accent: Bright terminal green #4ADE80
Pattern: 100% client-side JS, zero API calls
CSS namespace: .psb-* | Body class: page-ps-builder
Built: 2026-04-12 | v2: +20 UX improvements | v3: +14 Round 3 improvements | v3.1: Layout polish (stats in hero, dropdown filters, back-nav bottom)

---

Overview

A task-first PowerShell command builder for the full Microsoft IT admin stack. Guides users from "What do I want to do?" to a ready-to-run PowerShell command — no syntax memorisation, no AI hallucinations, no sign-up.

Covers 8 modules: Exchange Online, Microsoft Teams, Microsoft Graph (Entra ID), SharePoint (PnP), Azure, Active Directory, Group Policy, and Windows built-in.

Why This Tool Exists

Problem	Our Solution
AI generators hallucinate parameters	Curated, verified cmdlet data — zero hallucination
Desktop tools cost money / need install	100% free, browser-based, works offline
Existing tools are generic PowerShell	Focused on M365 + Azure + Windows admin tasks
Legacy modules mixed with modern	Modern modules only (Graph, not AzureAD/MSOnline)
No task-first UX	"What do you want to do?" + 68 task recipes
Beginners don't know how to run commands	"How to Run This" guide per recipe (install → connect → paste → disconnect)
No one explains piped commands	Pipeline step-by-step visual breakdown
No one warns about common pitfalls	⚠️ Common Mistakes callout on 12 high-risk recipes

---

Architecture

┌──────────────────────────────────────────────────────┐
│                     Hugo Build                        │
│                                                       │
│  data/ps_builder/       layouts/ps-builder/           │
│  ├── modules.toml  ──▶  list.html                    │
│  ├── cmdlets.toml  ──▶  (injects TOML as JSON        │
│  └── recipes.toml  ──▶   into window.__psBuilderData)│
│                                                       │
│  static/css/ps-builder.css                            │
│  static/js/ps-builder.js                              │
│  content/ps-builder/_index.md                         │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│                   Browser (Client)                    │
│                                                       │
│  window.__psBuilderData = {                           │
│    modules: [...],  // 8 modules                      │
│    cmdlets: [...],  // 65 cmdlets with params         │
│    recipes: [...]   // 68 task recipes                │
│  }                                                    │
│                                                       │
│  ps-builder.js reads data, renders 3 tabs:            │
│  ┌─────────┬─────────┬────────────┐                   │
│  │ Recipes │  Build  │ Reference  │                   │
│  └─────────┴─────────┴────────────┘                   │
│                                                       │
│  localStorage: history (20) + favourites              │
│  URL params: shareable state + recipe deep-links      │
└──────────────────────────────────────────────────────┘

---

Data Model

modules.toml (8 modules)

Module	Service	Category	Cmdlets
ExchangeOnlineManagement	Exchange Online	cloud	~10
MicrosoftTeams	Teams	cloud	~8
Microsoft.Graph	Entra ID / Graph	cloud	~10
PnP.PowerShell	SharePoint Online	cloud	~7
Az	Azure	cloud	~8
ActiveDirectory	On-prem AD	onprem	~7
GroupPolicy	GPO	onprem	~5
Windows Built-in	Windows	windows	~10

Each module includes: install_command, connect_command, disconnect_command, learn_url, min_version, requires_admin, install_note, category.

cmdlets.toml (65 cmdlets)

Each cmdlet: id, name, module, description, learn_url, last_reviewed, status, tags, parameters[] (name, type, required, description, placeholder, options for selects).

recipes.toml (68 recipes)

Each recipe: id, title, description, service, difficulty, tags, module, command, explanation, prerequisites, related_recipes.

---

v3 Feature Set (Complete)

Tab 1: Recipes (task-first entry point)

• "What do you want to do?" search bar with keyboard hint (/ to focus)
• Dropdown filters — Service (<select>) + Difficulty (<select>) next to search in one compact row (replaced pills in v3.1)
• 🔥 Quick Start — 8 most common tasks as pill buttons
• ⭐ My Favourites — starred recipes shown first (localStorage)
• 🎲 Surprise Me — random recipe discovery
• View toggle — 📋 List / 📂 Grouped by Service
• Search highlighting — matching terms bolded in accent
• Tags visible on cards — #mailbox, #security, etc.
• Expand chevrons ▸/▾ — clear clickability indicator
• 📋 How to Run This — collapsible guide per recipe (install → connect → paste → disconnect)
• 🔍 Pipeline breakdown — step-by-step visual for piped commands
• ⚠️ Common Mistakes — warning callout on 12 high-risk recipes
• Related Recipes — clickable links to related tasks
• Copy / Copy + Prerequisites / Download .ps1 / 🔗 Share / 🔧 Customise →
• Recipe deep-links — ?recipe=exo-shared-mailbox-create
• A3: Export all per service — download all Exchange recipes as one .ps1
• Suggest a Recipe CTA → Feedback portal

Tab 2: Build (visual command assembly)

• Module categories — ☁️ Cloud / 🏢 On-Prem / 🖥️ Windows filter tabs
• Step numbers — ① ② ③ visual progress
• Module info card — install, connect, docs link, notes
• Cmdlet search within module
• Visual parameter form — required highlighted, type-appropriate inputs, tooltips
• Live auto-preview — command updates as you type (debounced 300ms)
• ⚡ Build Command button + Ctrl+Enter shortcut
• Output — syntax-highlighted with copy/download/share

Tab 3: Reference (lightweight lookup)

• Searchable across all modules
• Accordion per module — click to expand
• Load → button opens cmdlet in Build tab
• Docs ↗ link to Microsoft Learn

Global Features

• Stats banner — 68 recipes · 65 cmdlets · 8 modules · $0
• Collapsible history with badge count (last 20)
• FAQ — 8 questions with FAQPage JSON-LD (global schema)
• Cross-links — Licensing Simplifier, Cert Guides, Prompts, Copilot Readiness
• Feedback CTA bar
• Print-friendly CSS — clean recipe cheat sheets
• URL state — tab, filters, search, module, cmdlet, recipe all in URL
• Keyboard shortcuts — / search, Enter expand, Ctrl+Enter build
• Reduced motion support
• WebApplication + FAQPage + BreadcrumbList JSON-LD schemas

---

Colour System

:root {
  --psb-accent: #4ADE80;         /* Bright terminal green */
  --psb-accent-hover: #86EFAC;
  --psb-accent-dim: rgba(74, 222, 128, 0.15);
  --psb-accent-glow: rgba(74, 222, 128, 0.25);
}

---

File Structure

aguidetocloud-revamp/
├── content/ps-builder/_index.md          # Hugo page (8 FAQs, SEO)
├── layouts/ps-builder/list.html          # Template (3 tabs, stats, quick start)
├── static/css/ps-builder.css             # ~20KB, .psb-* namespace
├── static/js/ps-builder.js              # ~35KB, IIFE pattern, v3
├── data/ps_builder/
│   ├── modules.toml                      # 8 modules
│   ├── cmdlets.toml                      # 65 cmdlets + params (~51KB)
│   └── recipes.toml                      # 68 recipes (~39KB)

---

Site Integration

Integration	Details
Nav dropdown	⚡ PowerShell Builder in Toolkit
Free Tools page	Card with --card-accent: #4ADE80
Body class	page-ps-builder in baseof.html
Nav accent	Terminal green border in style.css
Back-nav	→ "Toolkit"
Feedback CTA	Shared partial with tool=ps-builder

---

Maintenance

Frequency	Task
Monthly	Review cmdlets for deprecation/new cmdlets
Quarterly	Verify MS Learn URLs still valid
On announcement	Add new cmdlets if modules update
On feedback	Add most-requested recipes via Feedback portal

Data freshness fields

• last_reviewed on each cmdlet
• status = "current" | "legacy"
• module.min_version

---

Competitive Advantage

Feature	AI Generators	PSForge	PoshGUI	Our Tool
Free + web + no signup	✅	❌	✅	✅
M365 admin focused	❌	Partial	❌	✅
Task-first recipes	❌	❌	❌	✅
"How to Run" beginner guide	❌	❌	❌	✅
Pipeline visual breakdown	❌	❌	❌	✅
Common Mistakes warnings	❌	❌	❌	✅
Favourite recipes	❌	❌	❌	✅
Recipe deep-links	❌	❌	❌	✅
No hallucination risk	N/A	N/A	N/A	✅
Works offline	❌	✅	❌	✅

---

Gotchas & Lessons Learned

Gotcha	Fix
safeJS required on jsonify	Without it, Hugo minifier wraps JSON in backticks = broken
cache_version must be bumped on EVERY JS/CSS deploy	CDN (Cloudflare) serves stale files if URL doesn't change
Custom hero (not tool-hero.html partial)	Stats bar is inside the hero — can't use the shared partial
Filter pills cause "pill fatigue" with 8+ options	Use <select> dropdowns instead — same data, less visual noise
Back-nav at top feels redundant with tabs	Move to bottom of page — users need it after browsing, not before
data/ps_builder/ uses underscore (Hugo convention)	Content section content/ps-builder/ uses hyphen — both work but naming differs

Version History

Version	Date	Changes
v1	2026-04-12	Initial build: 3 tabs, 68 recipes, 65 cmdlets, 8 modules
v2	2026-04-12	20 UX improvements: expand chevrons, stats bar, recipe counts, Quick Start, live preview, favourites basics, keyboard shortcuts, deep-links, print CSS
v3	2026-04-12	14 Round 3 improvements: "How to Run" guide, pipeline breakdown, common mistakes, search highlight, tags, grouped view, favourites with localStorage, random recipe, export per service, recipe share, shortcut hints
v3.1	2026-04-12	Layout polish: stats moved into hero (under title, white numbers), crisper subtitle, filter pills replaced with <select> dropdowns next to search (reduces vertical space), back-nav moved from top to bottom. ⚠️ Cache bust lesson: always bump cache_version in hugo.toml on JS/CSS deploys

---