msp-script-library CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is an MSP (Managed Service Provider) script library containing PowerShell scripts for automation, deployment, configuration, and management tasks across various platforms and vendors. Scripts are designed to be executed both interactively and via RMM (Remote Monitoring and Management) platforms.

Code Architecture

Script Structure Standard

All scripts follow a consistent three-part structure defined in script-template-powershell.ps1:

1. RMM Variable Declaration Section (top of file)

   • Comment block listing all required RMM variables
   • Format: ## PLEASE COMMENT YOUR VARIABLES DIRECTLY BELOW HERE IF YOU'RE RUNNING FROM A RMM
   • Each variable should be documented as a comment (e.g., ## $variableName)

2. Input Handling Section

   • All RMM-supplied variables come via environment variables ($env:VarName). NinjaRMM passes script preset variables to PowerShell as environment variables, so the script must read them via $env: at every use site. Bare $VarName references resolve to $null in true RMM mode and silently fall through to the interactive branch.
   • Detects execution context via $env:RMM — environment variables are strings, so compare against "1" not 1. Anything other than "1" is interactive mode.
   • Interactive mode: Prompts user with Read-Host for required inputs with validation loop. Write the result back to $env:Description so the rest of the script can keep referencing $env: consistently.
   • RMM mode: Uses pre-set environment variables passed by the RMM platform. Defaults for any optional variables (custom field names, state file paths, etc.) should be set at the top of the script by writing to $env: directly:

     if ([string]::IsNullOrEmpty($env:CustomFieldFooBoolean)) {
         $env:CustomFieldFooBoolean = "fooDetected"
     }
     

   • Sets $LogPath based on context:
     • SYSTEM-context script, interactive: $env:WINDIR\logs\
     • SYSTEM-context script, RMM: $env:RMMScriptPath\logs\ (fallback to $env:WINDIR\logs\ if $env:RMMScriptPath is null)
     • User-context script: $env:LOCALAPPDATA\dtc-logs\ — $env:WINDIR\logs\ requires admin and a user-context script will fail to write there
   • Always captures $env:Description for audit trail