pi-powershell

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. $var is 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.