A powerful, opinionated single-file PowerShell framework for quick and easy (but customizable) command line tools

Example.ps1 Contains the framework, along with some example usages showcasing all of the features, this is the best place to look to familiarize yourself with the framework

Template.ps1 Contains the cut down base of the framework with no comments, ready to be copy and pasted into your codebase

This framework was designed for cases where importing a seperate module is not viable, it is powerful, yet small (fitting into only a couple hundred lines). This means it is ideal for copying into the bottom of a script to add commonly required features when making a command line tool. It is opinionated, meaning it is designed to support a layout with commands that take arguments and flags, and then calls a function for the command, passing those parsed values in for use.

• Customizable help menu
• User-defined commands with matching functions
• Custom arguments
  • Default argument values
  • Required arguments
  • Argument groups for organization, including exclusive groups
  • Support for lists
  • Strong typed results
  • Custom type parsing
  • Custom requirements
• Custom flags

$scriptTitle = ''
$scriptFileName = ''
$scriptDesc = ''
$version = ''

$commands = @{
    'command-name' = @{
        Description = ''
        Order = 0
        Arguments = @{
            'argument-name' = @{
                Description = ''
                Order = 0
                Required = $false
                Type = 'STRING'
                Default = ''
            }
            'Group Name' = @{
                Group = $true
                Order = 0
                Required = $false
                Exclusive = $false
                Arguments = @{}
            }
        }
        Flags = @{
            'flag-name' = @{
                Description = ''
                Order = 0
            }
        }
    }
}

function command-name {
    param(
        [hashtable]$Arguments,
        [hashtable]$Flags
    )

    # Command code here
}

$commands = @{
    'command-name' = @{}
}

Properties:

• Description [string] | Required
• Order [int] | Required - Order to show in the help menu
• Arguments
• Flags

Arguments = @{
    'argument-name' = @{}
}

Properties:

• Description [string] | Required
• Order [int] | Required - Order to show in the help menu
• Required
• RequiredDescription [string] - Optional for more verbose error messages
• Type
• CustomType
• List [bool] - Does the argument take a list
• Default
• DefaultDescription [string] - Optional for the help menu

This property can either be a [bool] or a [ScriptBlock]:

# Custom Script Block
Requirements = {
    param(
        [Hashtable]$Arguments,
        [Hashtable]$Flags
    )

    return [bool]
}

This property can either be 'STRING', 'PATH', 'BOOLEAN', 'NUMBER', which will provide built-in parsing, or you can provide any string you want as a display value (will not provide parsing by default, see: Custom Type Parsing)

'argument-name' = @{
    CustomType = @{}
}

Properties:

• ReturnType [Type]
• Parser [ScriptBlock]

# Parser Script Block
{
    param(
        [System.Object]$Value
    )

    # return ReturnType or $null if invalid
}

This property can either be any [System.Object] (typically the same as your "Type") or a [ScriptBlock]:

# Custom Script Block
Default = {
    param(
        [Hashtable]$Arguments,
        [Hashtable]$Flags
    )

    # return calculated default
}

Defaults are applied all together, so one default argument cannot rely on another

Arguments = @{
    'Argument Group' = @{
        Group = $true
        Arguments = @{}
    }
}

Properties:

• Order [int] | Required - Order to show in the help menu
• Required [bool] - Require at least one argument in the group
• Exclusive [bool] - Only allow one argument in the group at a time

Flags = @{
    'flag-name' = @{}
}

Properties:

• Description [string] | Required
• Order [int] | Required - Order to show in the help menu