Shell Command Execution

📖 Best for: Developers / ops / platform admins — people who want AI to execute shell commands directly in their workspace (check services, archive files, test APIs, run scripts) without opening a terminal

📖 Reading time: 4 minutes

📖 In one sentence: YingClaw's native Shell tool that lets AI execute shell commands directly in the workspace, covering daily ops and dev. Runs safety policy checks before execution (dangerous-command blacklist + risk-tier confirmation), enforces timeout (5 min default) and output truncation (1 MB cap) during, hides sensitive env vars from child processes after. Invoked as part of the YingClaw conversation at any time — no standalone menu, all roles, supports Windows / macOS / Linux · PowerShell / Git Bash / Bash.

---

I. Core Value

Value	Description
Cross-platform consistency	One natural-language sentence runs on Windows / macOS / Linux — no need to memorize different commands per OS
Safety-first	Built-in blacklist auto-blocks rm -rf / format / mkfs / registry edits; mid-risk commands trigger a confirmation prompt
Configurable & isolated	Custom command black/whitelists via policy file; sensitive env vars are NOT exposed to child processes by default
Observable	Per-command 5-min timeout, 1 MB output cap — hang / snowball / leak have fallbacks

II. Main Capabilities

1. Cross-Platform Support

• Windows: PowerShell (default) · Git Bash (YingClaw's bundled runtime)
• macOS / Linux: Bash (system-provided)
• YingClaw auto-detects the OS and picks the right shell engine — no manual specification needed

2. Dangerous-Command Blacklist (Auto-Blocked)

• Always blocked: rm -rf / format / mkfs / reg add / reg delete and other destructive ops; subshell operators `...` / <(...) / >(...)
• Blocked commands explain why (which rule fired); no silent failure
• Users can customize the blacklist in the policy file

3. Risk-Tier Confirmation

• Low-risk (ls / cat / grep / curl test): execute directly
• Mid-risk (write files / install packages / start services / change config): prompt for confirmation
• High-risk (in blacklist): outright rejected
• In Full Autonomy Mode mid-risk commands run without confirmation

4. Configurable Policy

• Customize command black/whitelists via the security policy file: block / always confirm / fully allow three tiers
• Enterprises can govern uniformly; config changes take effect immediately — no YingClaw restart
• See Security Policy Configuration (coming soon) for syntax

5. Dual Shell-Engine Selection

• PowerShell: Windows default, suits the Windows ecosystem (Get-ChildItem / Test-Path / Get-Service)
• Bash: macOS / Linux default, suits the Unix toolchain (grep / sed / awk / curl)
• YingClaw picks the best engine automatically; users can hint with keywords ("run this in PowerShell")

6. Timeout & Output Control

• Timeout protection: per-command max 5 minutes (300 s), auto-kill on timeout, returns the cause
• Output truncation: 1 MB cap, with a "output too large, see file for full content" notice
• Background execution: & for long-running tasks

7. Environment-Variable Isolation

• Sensitive vars (GITLAB_TOKEN / AWS_SECRET_ACCESS_KEY, etc.) are NOT exposed to child processes by default
• Only safe variables (PATH / HOME / USERPROFILE) are passed through
• Command output is also filtered for sensitive info (keys / tokens / passwords)
• Users can explicitly inject vars in the conversation ("run this with env var $MY_VAR")

8. Complex Command Composition

• Pipe: cat file | grep pattern · Chain: cd /path && ./build.sh
• Redirect: echo hello > file.txt · Background: ./long-task &
• Variable expansion: $HOME / ${USER} · Glob expansion: *.md / **/file

III. Typical Use Cases

Use Case 1: Ops Health Check — "Is nginx running?"

# Linux / macOS
systemctl status nginx
# Windows
Get-Service nginx

YingClaw auto-picks the right command for your OS and renders the result as a table (service name / status / PID / listening port). A 30-second health check.

Use Case 2: Deployment & Backup — "Tar.gz this directory"

tar -czvf myapp-2026-08-27.tar.gz ./myapp/
# or zip (Windows-friendly): zip -r myapp.zip ./myapp/

After packing, YingClaw returns package size, file count, compression ratio, plus next-step suggestions ("upload to S3", "copy to remote", "commit to Git").

Use Case 3: API Testing — "Test this API with curl"

curl -i https://api.example.com/v1/users
# with auth
curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/me

YingClaw formats JSON responses (highlight + collapse), parses HTTP headers, distinguishes 2xx / 4xx / 5xx and gives diagnostic suggestions — much more intuitive than hand-typed curl.

Use Case 4: Container & Process Management

# port usage
lsof -i :8080                    # macOS / Linux
Get-NetTCPConnection -LocalPort 8080   # Windows
# container
docker ps && docker logs <id>

For complex cases like "find the process holding port 8080", YingClaw auto-chains commands: lsof to find PID → ps for details → kill to terminate — one instruction covers the full flow.

Use Case 5: Batch File Processing

# find and compress 7-day-old logs
find /var/log -name "*.log" -mtime +7 -exec gzip {} \;
# batch content search
grep -rn "TODO" src/ | wc -l

YingClaw prefers safe options (trash over rm, two-step find -print then find -delete), reducing the risk of accidental damage.

IV. Usage Guide

Step 1: Issue a command in natural language — describe directly in the conversation ("check if nginx is running", "tar.gz the docs directory"); YingClaw auto-translates and runs.

Step 2: View execution results — small output shown directly; large output (> 1 MB) auto-truncated with the file path; long tasks support progress feedback, result returned on completion.

Step 3: Handle confirmation prompts — read the command carefully, confirm only if correct; to cancel, just say "no" / "cancel". In Full Autonomy Mode mid-risk commands run without confirmation.

Step 4: Handle timeout / truncation — timeout: break the task down or run it in background (./long-task &); truncation: filter with grep / head, or redirect to a file (command > out.txt) and read with the file-read tool.

Step 5: Switch shell engines — YingClaw picks automatically; to force, say explicitly "Run this in PowerShell: Get-ChildItem" or "Run this in Bash: find . -name '*.md'".

Step 6: Delegate complex tasks — multi-step tasks get auto-decomposed via a todo list, with progress reports; interrupt to adjust direction at any time.

V. Best Practices

• Preview dangerous commands before running — read the generated command yourself; pay extra attention to state-changing commands like rm / mv / chmod / chown
• Use trash over rm — recoverable beats gone forever; YingClaw will prefer trash in its suggestions
• Pipes over temp files — cat file | grep pattern is more readable than grep pattern $(cat file)
• Specify the shell engine explicitly — cross-platform commands (dir vs ls) diverge a lot; for critical commands state explicitly which engine
• Inspect long output via file, not screen — outputs over 1000 lines should be redirected to a file and read via the file-read tool
• Background long-running tasks — anything over 1 minute (packing / build / test) should run with & + log redirection, not blocking the conversation
• Don't hardcode sensitive values in commands — reference via $VAR, not api_key="glpat-xxx" literally; YingClaw auto-filters sensitive values in output
• Small-batch dry-run first — for batch ops like find ... -delete / sed -i, run without -delete / -i first to see what would change, then run for real once verified