terminal-commands

name	terminal-commands
description	Terminal command patterns for Volatio to avoid hanging, never pipe to head/tail, use quick scripts, show output, timeout handling. Use when commands hang, output buffering issues, or process management needed.

terminal-commands

When to Use

• Commands appear to hang
• Need to run terminal commands without blocking
• Managing long-running processes
• Debugging command output issues

Golden Path: Avoid Hanging

Rule: If a command takes >10 seconds, you're probably stuck.

Use Quick Scripts

# ✅ GOOD: Scripts that exit quickly
bun packages/jobs/src/test-calendar-flow.ts       # Checks DB, exits in <3s
bun packages/jobs/src/trigger-sync.ts full-sync   # Queues job, exits in <3s

# ❌ BAD: Servers that run forever
bun packages/jobs/src/run.ts    # Runs forever!
pnpm dev                         # Runs forever!

Check Status Without Waiting

docker compose ps              # Instant
lsof -i :3000                  # Instant
curl -s http://localhost:3001/health  # 1-2 seconds max

CRITICAL: Watch Mode Flags

Many tools default to watch mode which blocks forever:

Vitest

# ❌ HANGS FOREVER - watch mode default
pnpm test
pnpm vitest

# ✅ RUN ONCE AND EXIT
pnpm test -- --run
pnpm vitest --run

Playwright

# ❌ BLOCKS - opens HTML server at localhost:9323
./scripts/e2e.sh
pnpm exec playwright test

# ✅ OUTPUTS AND EXITS
./scripts/e2e.sh --reporter=list
pnpm exec playwright test --reporter=list

Next.js/Dev Servers

# ❌ RUNS FOREVER - dev server
pnpm dev
pnpm --filter dashboard dev

# ✅ BUILD ONCE
pnpm build

CRITICAL: Never Pipe to head/tail

Piping to | head or | tail causes commands to hang indefinitely:

# ❌ NEVER DO THIS - Hangs forever:
bun script.ts 2>&1 | head -100
bun script.ts 2>&1 | tail -50
ssh server 'docker logs container' | head -50
ssh server 'command' | grep something

# ✅ DO THIS - Output streams directly:
bun script.ts 2>&1
ssh server 'docker logs container --tail 50'  # Use --tail flag

Why: Piping creates a buffer waiting for EOF. The command may complete but the pipe doesn't close cleanly.

Always Show Output

# ✅ GOOD: Show output directly
bun test-calendar-flow.ts 2>&1

# ❌ BAD: Hiding output
bun test > /dev/null 2>&1
bun test --silent

Background Process Handling

# ❌ BAD: Background + sleep pattern
bun run.ts &
sleep 30  # Agent appears frozen!

# ✅ GOOD: Use isBackground=true for servers
# (This is a Copilot tool flag, not a bash flag)

# ✅ GOOD: Kill after timeout
bun packages/jobs/src/run.ts &
JOB_PID=$!
sleep 10
kill $JOB_PID

Mandatory Rules

1. NEVER run long-running servers without isBackground=true
2. NEVER run interactive commands (wait for input forever)
3. NEVER use sleep longer than 5 seconds in foreground
4. NEVER pipe to | head or | tail
5. ALWAYS show command output immediately
6. ALWAYS use --run flag for Vitest
7. ALWAYS use --reporter=list for Playwright

SSH Commands

# ❌ NEVER pipe SSH output:
ssh server 'docker compose build' | tail -80  # Hangs!

# ✅ Let output stream directly:
ssh server 'docker compose build'

# ✅ For long builds, run in background on server:
ssh server 'nohup docker compose build > build.log 2>&1 &'
ssh server 'tail -f build.log'  # Check progress separately

Port Management

# Find what's on a port
lsof -i :3001

# Kill by port
lsof -ti:3001 | xargs kill -9

# Kill all dev server ports
make kill-servers

Vitest Watch Mode

Vitest runs in watch mode by default:

# ✅ Run once and exit
pnpm test -- --run

# ❌ Hangs forever
pnpm test
vitest