Usage

Command Line Usage

py-psscriptanalyzer provides PowerShell static analysis and formatting from the command line.

Basic Commands

# Analyze a single file
py-psscriptanalyzer script.ps1

# Analyze multiple files
py-psscriptanalyzer script1.ps1 module.psm1 manifest.psd1

# Analyze all PowerShell files recursively
py-psscriptanalyzer --recursive

# Format a PowerShell file
py-psscriptanalyzer --format script.ps1

Command Line Options

Option	Description	Example
`--severity`	Set severity level (Error, Warning, Information)	`--severity Error`
`--recursive`	Find PowerShell files recursively	`--recursive`
`--format`	Format files instead of analyzing	`--format`
`--output-format`	Output format (text, json, sarif)	`--output-format json`
`--output-file`	Write output to file	`--output-file results.json`
`--security-only`	Show only security issues	`--security-only`
`--style-only`	Show only style issues	`--style-only`
`--performance-only`	Show only performance issues	`--performance-only`
`--best-practices-only`	Show only best practice issues	`--best-practices-only`
`--dsc-only`	Show only DSC issues	`--dsc-only`
`--compatibility-only`	Show only compatibility issues	`--compatibility-only`
`--include-rules`	Include only specific rules	`--include-rules Rule1,Rule2`
`--exclude-rules`	Exclude specific rules	`--exclude-rules Rule1,Rule2`

Severity Levels

py-psscriptanalyzer uses hierarchical severity filtering:

Error: Only critical errors that must be fixed
Warning: Warnings and errors (default)
Information: All issues including informational messages

# Show only critical errors
py-psscriptanalyzer --severity Error script.ps1

# Show warnings and errors (default)
py-psscriptanalyzer --severity Warning script.ps1

# Show all issues
py-psscriptanalyzer --severity Information script.ps1

Environment Variables

Set the SEVERITY_LEVEL environment variable to change the default:

# Set default severity
export SEVERITY_LEVEL=Error
py-psscriptanalyzer script.ps1  # Uses Error level

# Command line always overrides environment variables
export SEVERITY_LEVEL=Error
py-psscriptanalyzer --severity Warning script.ps1  # Uses Warning level

Rule Filtering

By Category

Filter by PSScriptAnalyzer rule categories:

# Security-focused analysis
py-psscriptanalyzer --security-only script.ps1

# Style and formatting issues
py-psscriptanalyzer --style-only script.ps1

# Performance-related issues
py-psscriptanalyzer --performance-only script.ps1

# Best practice violations
py-psscriptanalyzer --best-practices-only script.ps1

# DSC-specific issues
py-psscriptanalyzer --dsc-only script.ps1

# Compatibility issues
py-psscriptanalyzer --compatibility-only script.ps1

By Specific Rules

Include or exclude specific PSScriptAnalyzer rules:

# Include only specific rules
py-psscriptanalyzer --include-rules PSAvoidUsingPlainTextForPassword,PSAvoidUsingConvertToSecureStringWithPlainText script.ps1

# Exclude specific rules
py-psscriptanalyzer --exclude-rules PSAvoidUsingWriteHost,PSAvoidUsingPositionalParameters script.ps1

# Combine with other filters
py-psscriptanalyzer --severity Error --security-only --exclude-rules PSAvoidDefaultValueSwitchParameter script.ps1

Output Formats

Text Output (Default)

Standard console output with color coding:

py-psscriptanalyzer script.ps1

JSON Output

Machine-readable JSON format:

# Output to console
py-psscriptanalyzer --output-format json script.ps1

# Save to file
py-psscriptanalyzer --output-format json --output-file results.json script.ps1

SARIF Output

Static Analysis Results Interchange Format for GitHub Code Scanning:

# Generate SARIF file for GitHub integration
py-psscriptanalyzer --output-format sarif --output-file powershell-analysis.sarif --recursive

Formatting

Format PowerShell files using Invoke-Formatter:

# Format a single file
py-psscriptanalyzer --format script.ps1

# Format multiple files
py-psscriptanalyzer --format script1.ps1 script2.ps1

# Format all PowerShell files recursively
py-psscriptanalyzer --format --recursive

Recursive Processing

Process all PowerShell files in the current directory and subdirectories:

# Analyze all PowerShell files
py-psscriptanalyzer --recursive

# Format all PowerShell files
py-psscriptanalyzer --format --recursive

# Combine with other options
py-psscriptanalyzer --recursive --severity Error --security-only

Exit Codes

py-psscriptanalyzer returns standard exit codes:

0: Success (no issues found or formatting completed)
1: Issues found or errors occurred
2: Invalid arguments or configuration

Examples

Basic Analysis

# Quick check with default settings
py-psscriptanalyzer MyScript.ps1

# Comprehensive analysis
py-psscriptanalyzer --recursive --severity Information

# Security audit
py-psscriptanalyzer --recursive --security-only --severity Error

Output to Files

# JSON report for CI/CD
py-psscriptanalyzer --recursive --output-format json --output-file analysis.json

# SARIF for GitHub Code Scanning
py-psscriptanalyzer --security-only --recursive --output-format sarif --output-file security.sarif

Custom Rule Sets

# Focus on critical security rules only
py-psscriptanalyzer --include-rules PSAvoidUsingPlainTextForPassword,PSAvoidUsingConvertToSecureStringWithPlainText --severity Error script.ps1

# Exclude noisy style rules
py-psscriptanalyzer --exclude-rules PSAvoidUsingWriteHost,PSAvoidSemicolonsAsLineTerminators script.ps1

Pre-commit Hook Usage

For pre-commit hook configuration, see the Configuration documentation.

Integration with IDEs

VS Code

py-psscriptanalyzer can be integrated with VS Code through tasks or extensions that support external linters.

Other Editors

Any editor that supports external command execution can integrate py-psscriptanalyzer for PowerShell analysis.