powershell-safe-vars

PowerShell: Safe Variables, Quoting, and One-Liners

When to use

Use this when writing or editing PowerShell (pwsh) commands/scripts inside Codex tool calls, especially for automations and one-liner scripts.

Problems this prevents

PowerShell has automatic variables (some are read-only / constant), and variable names are case-insensitive. Accidentally assigning to one of these (e.g. $HOME, $Host) can cause a script to fail with errors like “Cannot overwrite variable … because it is read-only or constant.”

PowerShell also parses quoting, pipes, redirection, and command substitution differently than Bash. Copying Bash snippets directly can produce ParserError, Missing file specification after redirection operator, The term 'from' is not recognized, or An empty pipe element is not allowed.

Workflow

1. Pick “safe” variable names

• Prefer descriptive names like $userHome, $codexHome, $installRoot, $sessionDir.
• Avoid short/common names that collide with automatic variables, including:
  • $HOME (often constant) → use $userHome
  • $Host (automatic variable) → use $hostInfo / $hostProc
  • $PID, $PSVersionTable, $Error, $Matches, $Profile, $PSScriptRoot, $PSCommandPath
• Remember: $home and $HOME are the same variable.

1. If you must reuse a risky name, change it immediately

• Rename the local variable to a safe name and update all references.

1. Keep “tool-call scripts” failure-loud

• Start scripts with: $ErrorActionPreference='Stop'
• Set timeouts explicitly in the tool call (e.g. timeout_ms) for long operations.

1. Avoid string-interpolation parsing traps

• If a variable is immediately followed by :, PowerShell can treat it like a scoped variable reference and throw: “Variable reference is not valid. ':' was not followed by a valid variable name character.”
• Fix by using one of:
  • "${var}:suffix" (brace the variable)
  • ("{0}:{1}" -f $var, $suffix) (format operator)

1. Treat optional env vars as optional

• Some environments won’t set expected variables like $env:CODEX_HOME.
• Prefer defensive fallbacks, e.g.:
  • $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }