POWERSHELL_COMMAND_REFERENCE.md

PowerShell Command Reference for Kiro

CRITICAL: Stop using Unix commands on PowerShell. Use these instead.

Quick Reference

Unix	PowerShell	Example
head -n 50	Select-Object -First 50	pytest ... | Select-Object -First 50
tail -n 50	Select-Object -Last 50	pytest ... | Select-Object -Last 50
grep "pattern"	Select-String "pattern"	Get-Content file.txt | Select-String "error"
grep -r "pattern"	Select-String -Path "**/*.txt" -Pattern "pattern"	Select-String -Path "**/*.py" -Pattern "TODO"
cat file.txt	Get-Content file.txt	Get-Content test.log
ls	Get-ChildItem or ls (alias works)	Get-ChildItem
mkdir dir	New-Item -ItemType Directory -Path dir	New-Item -ItemType Directory -Path src/tests
rm file	Remove-Item file	Remove-Item old.txt
rm -r dir	Remove-Item -Recurse -Force dir	Remove-Item -Recurse -Force build/
cp file1 file2	Copy-Item file1 file2	Copy-Item src.py dest.py
cp -r dir1 dir2	Copy-Item -Recurse dir1 dir2	Copy-Item -Recurse src/ backup/
find . -name "*.py"	Get-ChildItem -Recurse -Filter "*.py"	Get-ChildItem -Recurse -Filter "*.py"
wc -l file	(Get-Content file | Measure-Object -Line).Lines	(Get-Content test.py | Measure-Object -Line).Lines
echo "text"	Write-Host "text"	Write-Host "Starting tests"

Common Patterns

Get first N lines of output

# Unix: command | head -20
# PowerShell:
command | Select-Object -First 20

Get last N lines of output

# Unix: command | tail -20
# PowerShell:
command | Select-Object -Last 20

Search for pattern in output

# Unix: command | grep "error"
# PowerShell:
command | Select-String "error"

Search for pattern in files

# Unix: grep -r "TODO" src/
# PowerShell:
Select-String -Path "src/**/*.py" -Pattern "TODO"

Count lines in file

# Unix: wc -l file.txt
# PowerShell:
(Get-Content file.txt | Measure-Object -Line).Lines

List files recursively

# Unix: find . -name "*.py"
# PowerShell:
Get-ChildItem -Recurse -Filter "*.py"

Why This Matters

1. Performance: PowerShell cmdlets work with .NET objects, not text streams. They're faster.
2. Compatibility: Unix commands don't work on PowerShell (or work slowly via WSL).
3. Cost: Every failed command wastes API credits. Using native commands reduces errors.
4. Clarity: PowerShell commands are explicit and readable.

Examples from Recent Work

WRONG (Unix on PowerShell)

python -m pytest DivineOS/tests/unit/ -q --tb=line 2>&1 | head -150
# Error: head is not recognized

RIGHT (PowerShell native)

python -m pytest DivineOS/tests/unit/ -q --tb=line 2>&1 | Select-Object -First 150
# Works perfectly

WRONG (Unix grep)

Get-Content file.txt | grep "error"
# Error: grep is not recognized

RIGHT (PowerShell Select-String)

Get-Content file.txt | Select-String "error"
# Works perfectly

Key Differences

Unix pipes pass text:

command1 | command2  # text stream

PowerShell pipes pass objects:

command1 | command2  # .NET objects with properties

This means PowerShell is actually MORE powerful—you can filter by object properties, not just text patterns.

Enforcement Rule

From now on:

• Use Select-Object -First N instead of head -n N
• Use Select-Object -Last N instead of tail -n N
• Use Select-String instead of grep
• Use Get-ChildItem instead of find
• Use Get-Content instead of cat

This will save time, reduce errors, and use fewer credits.