command-execution-principles

Command Execution Principles

Security

• ❌ exec(userInput), shell("rm " + userFile)
• ✅ Argument lists (no shell string concat), validate/sanitize all args
• Never run as root/admin without explicit human approval. Elevated perms required → STOP and request auth.
• Least-privilege service accounts

Portability

• Use language stdlib over shell commands (file I/O APIs instead of cat/cp/mv)
• Test on all target OS (path joining functions, not / concatenation)

Error Handling

• Check exit codes (non-zero = failure)
• Capture + log stderr
• Set timeouts for long-running
• Handle "command not found" gracefully

Non-Interactive Mode (MANDATORY for AI Agents)

AI agents CANNOT interact with interactive prompts. All commands MUST run non-interactively. A stuck prompt = a stuck agent = wasted time.

Environment Variables (set before ANY npm/yarn/pnpm command)

export CI=true               # Signals non-interactive environment to most tools
export npm_config_yes=true   # npm: auto-accept all prompts
export YARN_ENABLE_IMMUTABLE_INSTALLS=false  # Yarn: don't fail on lockfile changes

npm / npx

# ✅ CORRECT — always use --yes for npx
npx -y create-vite@latest ./my-app -- --template vue-ts
npx -y create-next-app@latest ./my-app --ts --eslint --app --use-npm

# ✅ CORRECT — npm install (CI=true suppresses prompts)
CI=true npm install
CI=true npm ci              # Preferred for reproducible installs

# ❌ WRONG — interactive, WILL HANG
npx create-vite@latest my-app
npm init
npm create vite

Scaffolding Tools (create-vite, create-next-app, etc.)

Every scaffolding tool has a non-interactive mode. You MUST find and use it.

1. Run --help first to discover non-interactive flags before scaffolding
2. Always pass all required options (template, name, etc.) as CLI flags
3. Common patterns:
   • create-vite: --template <template> (must specify template to skip prompt)
   • create-next-app: --ts --eslint --app --use-npm (pass all choices as flags)
   • create-react-app: pass project name as argument
   • npm init <initializer>: use npm create <initializer> -- <flags> with --yes or template flags
4. If a tool still prompts, pipe yes | as last resort: yes | npx -y create-tool ...