By name: pi-powershell description: >- PowerShell tools for Windows — background processes, system operations, remote management. Use when: starting background dev servers, managing Windows processes/services, killing by port, running .cmd/.bat files, any task where Git Bash hangs or lacks Windows integration. Triggers: background process, start server, Windows service, kill process, PowerShell, pwsh, batch file, .cmd, npm run dev in background, port in use, Get-Process, Stop-Process.
PowerShell Tools
6 tools for Windows system operations and background processes. Complements the built-in bash tool.
Tools
| Tool | Purpose |
|---|---|
powershell |
Execute a PowerShell command. Process dies after execution, like bash. |
pwsh-start-job |
Start a background OS process (detached, persists across tool calls) |
pwsh-get-job |
Check job status by name, or list all tracked jobs |
pwsh-stop-job |
Stop a background job by name |
pwsh-remove-job |
Remove job tracking + clean up log files |
pwsh-get-job-output |
Read captured stdout/stderr from a job |
When to Use PowerShell vs Bash
| Task | Tool | Why |
|---|---|---|
ls, grep, find, git |
bash |
Works fine in Git Bash |
npm install, npm test |
bash |
Works fine in Git Bash |
| Background dev servers | pwsh-start-job |
& hangs Git Bash |
| Kill process by port | powershell |
Needs Get-NetTCPConnection |
| Windows services | powershell |
Needs Get-Service / Start-Service |
| Process management | powershell |
Needs Get-Process / Stop-Process |
Common Patterns
Background Dev Server
pwsh-start-job name="dev" command="npm run dev" workingDirectory="C:/dev/myapp"
Then check with pwsh-get-job name="dev", read output with pwsh-get-job-output name="dev", stop with pwsh-stop-job name="dev".
Kill by Port
powershell "Get-NetTCPConnection -LocalPort 5173 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }"
Check Running Node Processes
powershell "Get-Process | Where-Object {$_.ProcessName -like '*node*'} | Select-Object Id, ProcessName, CPU"
Quoting Rules
PowerShell quoting differs from bash:
- Single quotes
'text'— literal string. Escape with''(double single-quote). - Double quotes
"text"— variable expansion.$varis interpolated. - Backtick
`is the escape character, not backslash. - Env vars:
$env:NODE_ENV(not$NODE_ENV).
For detailed quoting patterns and gotchas, see references/quoting.md.
Background Jobs — Output Capture
By default, stdout and stderr are merged into one temp log file (PowerShell *> — all streams).
You can control this with stdout and stderr parameters on pwsh-start-job:
stdout: file path, or"null"to discard. Default: temp file.stderr: file path,"stdout"to merge, or"null"to discard. Default:"stdout"(merged).
For full job lifecycle and advanced output options, see references/background-processes.md.
Batch Files (.cmd / .bat)
npm, yarn, pnpm are .cmd batch files on Windows. The powershell tool auto-detects failures
and retries with cmd /c. You can also wrap explicitly:
powershell "cmd /c 'npm run build'"
The pwsh-start-job tool handles batch files automatically.
PSSessions (Remote Management)
A PSSession is a persistent PowerShell connection to a remote Windows machine. Use it when you need to:
- Execute commands on a remote server (deploy, manage IIS, check services)
- Maintain state across multiple remote commands (imported modules, variables)
- Manage multiple remote machines in a workflow
PSSessions are only for remote connections — never use them as a local persistent shell
(that would break pi's /tree and /fork behavior).
Tools: pwsh-create-session (with computerName + credentials) and pwsh-close-session.
For setup, authentication options, and remote management patterns, see references/psession.md.