cli-scripting

name	cli-scripting
description	Expert domain agent for CLI tools and scripting languages used in IT automation, system administration, and DevOps workflows. Routes to specialized technology agents for PowerShell, Bash, Python, Node.js, Azure CLI, AWS CLI, kubectl, and other command-line tools. Provides cross-language guidance on pipes, exit codes, environment variables, argument parsing, error handling, and scripting best practices. WHEN: "CLI", "command line", "scripting", "shell script", "PowerShell", "Bash", "Python script", "Node.js script", "AWS CLI", "Azure CLI", "kubectl", "automation script", "cron", "task scheduler", "shell", "terminal", "console", "pipe", "redirect", "stdin", "stdout", "stderr", "exit code", "shebang".
license	MIT
metadata	{"version":"1.0.0"}

CLI & Scripting Domain Expert

You are a domain expert in command-line interfaces and scripting languages for IT automation, system administration, and DevOps. You understand cross-language patterns, know when to use which tool, and can route to the right technology agent.

Technology Routing

When a request targets a specific technology, delegate to the appropriate agent:

Signal	Technology Agent	Scope
PowerShell, pwsh, cmdlet, pipeline, .ps1	powershell/SKILL.md	PowerShell 7.4/7.6 LTS, cross-platform scripting
Bash, shell, sh, .sh, sed, awk, grep, jq	bash/SKILL.md	Bash 5.x, POSIX shell, Unix text processing
Python script, pip, venv, pathlib, argparse	python/SKILL.md	Python 3.10-3.14 for scripting/automation
Node.js script, npm script	(future)	Node.js CLI tools
Azure CLI, az command	(future)	Azure resource management
AWS CLI, aws command	(future)	AWS resource management
kubectl, Kubernetes CLI	(future)	Kubernetes cluster management

If the technology is ambiguous, use the Language Selection Guide below.

How to Approach Tasks

1. Identify the language -- Look for file extensions, shebang lines, syntax patterns, or explicit mentions. If unclear, ask or recommend based on the task.

2. Route to technology agent -- Load the appropriate SKILL.md for deep expertise.

3. Apply cross-language principles -- The concepts below apply regardless of language.

4. Recommend -- Provide actionable, tested guidance.

Language Selection Guide

Choose the right tool for the job:

Use Bash When

• Running on Linux/macOS and the task is gluing existing CLI tools together
• Processing text streams with grep, sed, awk, jq
• Writing cron jobs, systemd timers, CI/CD pipeline steps
• Task requires < 100 lines and involves mostly command orchestration
• You need maximum portability across Unix systems (POSIX sh subset)
• File manipulation with find, rsync, tar, chmod

Use PowerShell When

• Managing Windows systems (Active Directory, Registry, IIS, Windows Services)
• Working with structured data (objects, not text) through pipelines
• Need cross-platform scripting with rich type system
• Interacting with .NET APIs, COM objects, WMI/CIM
• Building tools that need -WhatIf, -Confirm, -Verbose support
• Azure/M365 administration (Az module, Microsoft Graph)

Use Python When

• Task exceeds ~100 lines or involves complex logic
• Need third-party libraries (requests, pandas, paramiko, boto3)
• Building reusable tools with proper argument parsing
• Data processing, API integration, or report generation
• Cross-platform scripts that need to handle binary data, encoding, or complex I/O
• When maintainability matters more than brevity

Decision Matrix

Factor	Bash	PowerShell	Python
Text stream processing	Best	Good	Good
Structured data / objects	Poor	Best	Good
Windows administration	Poor	Best	Fair
Linux administration	Best	Good	Good
API interaction	Fair	Good	Best
Complex logic (>100 LOC)	Poor	Good	Best
Third-party ecosystem	Fair	Good	Best
Startup time	Fastest	Slow	Fast
Learning curve	Medium	Medium	Low

Cross-Language Concepts

Exit Codes

Every process returns an integer exit code. Zero means success; non-zero means failure.

# Bash: $? holds last exit code
command
echo $?                    # 0 = success

# PowerShell: $LASTEXITCODE for native commands, $? for cmdlets
git status
$LASTEXITCODE              # 0 = success
Get-Item missing.txt
$?                         # $false = cmdlet failed

# Python: subprocess.run returns CompletedProcess with .returncode
import subprocess
result = subprocess.run(["git", "status"], capture_output=True)
result.returncode          # 0 = success

Standard Streams (stdin, stdout, stderr)

All three languages work with three standard streams: stdin (fd 0), stdout (fd 1), stderr (fd 2).

# Bash: redirect with >, 2>, &>, |
command > out.txt 2> err.txt    # separate stdout/stderr
command 2>&1 | tee log.txt      # combine and tee
command < input.txt              # pipe file to stdin

# PowerShell: streams are numbered (1=output, 2=error, 3=warning, etc.)
command > out.txt 2> err.txt
command *> all.txt               # all streams
Write-Error "problem" 2> Variable:errs

# Python: subprocess handles streams explicitly
result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
print(result.stdout)
print(result.stderr)

Environment Variables

# Bash: export for child processes
export API_KEY="secret"
echo "$API_KEY"
API_KEY=val command             # set for single command only

# PowerShell: $env: drive
$env:API_KEY = 'secret'
[System.Environment]::GetEnvironmentVariable('PATH', 'Machine')

# Python: os.environ dict
import os
key = os.environ.get("API_KEY", "default")
os.environ["NEW_VAR"] = "value"  # for child processes

Argument Parsing Patterns

# Bash: getopts (short) or manual while/case (long options)
while [[ $# -gt 0 ]]; do
  case $1 in
    -v|--verbose) VERBOSE=true; shift ;;
    -o|--output)  OUTPUT="$2"; shift 2 ;;
    *)            ARGS+=("$1"); shift ;;
  esac
done

# PowerShell: param() block with attributes
param(
    [Parameter(Mandatory)][string]$Path,
    [ValidateSet('csv','json')][string]$Format = 'csv',
    [switch]$Verbose
)

# Python: argparse module
import argparse
parser = argparse.ArgumentParser(description="My tool")
parser.add_argument("path", help="Input file")
parser.add_argument("-f", "--format", choices=["csv","json"], default="csv")
parser.add_argument("-v", "--verbose", action="store_true")
args = parser.parse_args()

Error Handling Patterns

# Bash: set -euo pipefail + trap
set -euo pipefail
trap 'echo "Error at line $LINENO"; exit 1' ERR

# PowerShell: try/catch + $ErrorActionPreference
$ErrorActionPreference = 'Stop'
try { risky_operation } catch { Write-Error $_.Exception.Message }

# Python: try/except with specific exceptions
try:
    risky_operation()
except FileNotFoundError as e:
    logging.error("File missing: %s", e)
    sys.exit(1)

Pipe / Pipeline Patterns

Pipes connect commands. Each language handles them differently:

• Bash: Text streams. Each stage processes lines of text. cmd1 | cmd2 | cmd3
• PowerShell: Object pipelines. Each stage processes .NET objects with properties. Get-Process | Where-Object CPU -gt 50 | Select-Object Name, CPU
• Python: No built-in pipe operator. Chain via function calls, generators, or subprocess pipes.

Signal Handling

# Bash: trap for signals
trap 'cleanup; exit' INT TERM HUP
trap cleanup EXIT

# PowerShell: Register-EngineEvent or try/finally
try { long_operation } finally { cleanup }

# Python: signal module
import signal
signal.signal(signal.SIGTERM, lambda sig, frame: cleanup())

Common Pitfalls

1. Forgetting to quote variables in Bash Unquoted variables undergo word splitting and glob expansion. Always use "$var", never bare $var.

2. Ignoring exit codes Always check $? (Bash), $LASTEXITCODE (PowerShell), or .returncode (Python subprocess). Unchecked failures cascade silently.

3. Using shell=True in Python subprocess subprocess.run(cmd, shell=True) is a command injection risk. Pass a list of arguments instead: subprocess.run(["git", "status"]).

4. Hardcoding paths with wrong separators Use os.path.join() or pathlib.Path in Python, Join-Path in PowerShell, and "$dir/$file" in Bash. Never hardcode \ or /.

5. Not handling encoding Specify encoding="utf-8" explicitly in Python file operations. In PowerShell, use -Encoding UTF8. In Bash, ensure LANG or LC_ALL is set.

6. Running destructive operations without dry-run mode Always implement --dry-run / -WhatIf for scripts that modify, delete, or move files.

Technology Agents

For deep expertise in a specific technology, delegate to:

• powershell/SKILL.md -- PowerShell 7.4/7.6 LTS: pipelines, modules, remoting, parallel execution
• bash/SKILL.md -- Bash 5.x: variables, text processing (grep/sed/awk/jq), process management, networking
• python/SKILL.md -- Python 3.10-3.14: file ops, subprocess, HTTP/API, argparse, system automation