PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling.
Critical patterns and pitfalls for Windows PowerShell.
| ❌ Wrong | ✅ Correct |
|---|---|
if (Test-Path "a" -or Test-Path "b") | if ((Test-Path "a") -or (Test-Path "b")) |
if (Get-Item $x -and $y -eq 5) | if ((Get-Item $x) -and ($y -eq 5)) |
Rule: Each cmdlet call MUST be in parentheses when using logical operators.
Rule: On Windows the shell is PowerShell. Do not use Unix commands — they are not available and cause "term not recognized" errors.
&&In Bash, && chains commands (run second only if first succeeds). In Windows PowerShell 5.x (default on Windows), && is not supported and produces a syntax/operator error. Always use ; to chain commands in this project (see configs/project.yaml → shell_forbidden: "&&").
| ❌ Wrong (fails on Windows) | ✅ Correct |
|---|---|
npm run lint && npm run typecheck | npm run lint ; npm run typecheck |
cd src ; npm run build && npm run test | cd src ; npm run build ; npm run test |
Rule: When suggesting or generating terminal commands for this repo, never use &&. Use ; only.
| Unix (Bash) | PowerShell equivalent |
|---|---|
head -n 50 | Select-Object -First 50 |
tail -n 50 | Select-Object -Last 50 |
cat file | Get-Content file |
ls | Get-ChildItem |
grep "x" (command) | Select-String "x" or use the Cursor Grep tool |
cmd1 && cmd2 | cmd1 ; cmd2 (or run separately) |
Example: to list first 50 items from a pipeline use ... | Select-Object -First 50, not ... | head -50.
| Purpose | ❌ Don't Use | ✅ Use |
|---|---|---|
| Success | ✅ ✓ | [OK] [+] |
| Error | ❌ ✗ 🔴 | [!] [X] |
| Warning | ⚠️ 🟡 | [*] [WARN] |
| Info | ℹ️ 🔵 | [i] [INFO] |
| Progress | ⏳ | [...] |
Rule: Use ASCII characters only in PowerShell scripts.
| ❌ Wrong | ✅ Correct |
|---|---|
$array.Count -gt 0 | $array -and $array.Count -gt 0 |
$text.Length | if ($text) { $text.Length } |
| ❌ Wrong | ✅ Correct |
|---|---|
"Value: $($obj.prop.sub)" | Store in variable first |
Pattern:
$value = $obj.prop.sub
Write-Output "Value: $value"
| Value | Use |
|---|---|
| Stop | Development (fail fast) |
| Continue | Production scripts |
| SilentlyContinue | When errors expected |
| Pattern | Use |
|---|---|
| Literal path | C:\Users\User\file.txt |
| Variable path | Join-Path $env:USERPROFILE "file.txt" |
| Relative | Join-Path $ScriptDir "data" |
Rule: Use Join-Path for cross-platform safety.
| Operation | Syntax |
|---|---|
| Empty array | $array = @() |
| Add item | $array += $item |
| ArrayList add | `$list.Add($item) |
| ❌ Wrong | ✅ Correct |
|---|---|
ConvertTo-Json | ConvertTo-Json -Depth 10 |
Rule: Always specify -Depth for nested objects.
| Operation | Pattern |
|---|---|
| Read | `Get-Content "file.json" -Raw |
| Write | `$data |
| Error Message | Cause | Fix |
|---|---|---|
| "parameter 'or'" | Missing parentheses | Wrap cmdlets in () |
| "Unexpected token" | Unicode character | Use ASCII only |
| "Cannot find property" | Null object | Check null first |
| "Cannot convert" | Type mismatch | Use .ToString() |
# Strict mode
Set-StrictMode -Version Latest
$ErrorActionPreference = "Continue"
# Paths
$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
# Main
try {
# Logic here
Write-Output "[OK] Done"
exit 0
}
catch {
Write-Warning "Error: $_"
exit 1
}
Remember: PowerShell has unique syntax rules. Parentheses, ASCII-only, and null checks are non-negotiable.