terminal-command-safety

name	terminal-command-safety
description	Safe terminal command patterns — backtick escaping, output capture, and hang prevention
lastReviewed	2026-04-30T00:00:00.000Z

Terminal Command Safety

Detailed patterns and examples for safe terminal command execution in AI agent contexts.

Decision Table

Content Type	Safe Approach	Why
Contains backticks	Use temp file	Backticks break in all shells
Multi-line text	Use temp file	Heredocs can desync terminal
Both quote types	Use temp file	Can't escape both cleanly
Dollar signs ($)	Single-quoted heredoc or temp file	Prevents interpolation
Plain text only	Inline is safe	No shell metacharacters
Long-running (>15s)	mode=async	Prevents timeout
Interactive prompt	Pre-answer with flags	--yes, --no-edit
Needs full output	Redirect to file, then read	Output can be truncated

Backtick Hazard — Details

Backticks in terminal command arguments break across all shells:

• bash/zsh: backtick = command substitution (echo "uselshere" executes ls)
• PowerShell: backtick = escape character (echo "usen here"` inserts newline)

Ref: vscode#295620

Safe Pattern (bash)

# Write content to temp file (single-quoted delimiter prevents interpolation)
cat > /tmp/body.md << 'EOF'
## Changes
- Added `MyClass` to the module
- Updated `config.py`
EOF

# Pass file to command
gh pr create --title "My PR" --body-file /tmp/body.md
rm /tmp/body.md

Safe Pattern (PowerShell)

$body = @'
## Changes
- Added `MyClass` to the module
'@
$body | Out-File -Encoding utf8 "$env:TEMP\body.md"
gh pr create --title "My PR" --body-file "$env:TEMP\body.md"
Remove-Item "$env:TEMP\body.md"

Output Capture — Examples

Refs: vscode#308610, vscode#308048, vscode#307173

Redirect to file

npm run build 2>&1 | Out-File -Encoding utf8 "$env:TEMP\build-output.txt"
Get-Content "$env:TEMP\build-output.txt" -Tail 50

Pipe through Out-String

git log --oneline -20 | Out-String

Sentinel pattern

npm test 2>&1; echo "EXIT_CODE:$LASTEXITCODE"

Alt-buffer avoidance

• git log not git log | less (set $env:GIT_PAGER="cat")
• Get-Help not man
• gh issue view --json not gh issue view (which opens a pager)

Terminal Hanging — Examples

Refs: vscode#308610, vscode#306490

Async mode selection

mode=async for: npm start, dotnet run, docker compose up, long test suites
mode=sync with timeout=30000 for: npm install, git operations, single test files

Pre-answer interactive prompts

npm install --yes
rm -rf (not rm -ri)
az login --use-device-code
git commit --no-edit (merge commits)

Network timeouts

npm install --prefer-offline --no-audit
curl --max-time 30 --connect-timeout 10 $url