Automation scripts tend to start life as “just a quick helper,” but in most environments they inevitably become part of operational reality: they run on schedules, touch production systems, and get passed from one engineer to the next. The difference between a script that quietly saves hours and one that creates outages is rarely the chosen language; it’s the discipline in how the script is designed, reviewed, executed, and maintained.
This guide focuses on scripting best practices specifically for IT administrators and system engineers: the habits and patterns that make automation safe, predictable, and supportable. The goal is not to force enterprise software engineering on every one-liner. Instead, it’s to help you recognize when a script is crossing the line from “temporary” to “operational,” and to apply the smallest set of practices that materially reduces risk.
The sections build from fundamentals (purpose, scope, interfaces) to operational concerns (error handling, idempotency, logging, security) and then to lifecycle practices (version control, testing, packaging, deployment). Along the way, you’ll see concrete examples in PowerShell and Bash because they’re common in IT shops, with occasional Python/Azure CLI where it clarifies a point.
Decide what kind of script you are writing (and why it matters)
The first best practice is classification. Not every script needs the same rigor, and applying heavyweight ceremony to a disposable diagnostic can waste time. But treating an operational script like a disposable snippet is how outages happen.
A useful mental model is to separate scripts into three categories. A “one-off” script is something you run interactively to answer a question or perform a quick bulk action under direct supervision. An “operator-run” script is executed manually but repeatedly by you or your team, often during maintenance windows or incident response. A “fully automated” script is invoked by schedulers, pipelines, configuration management systems, or event triggers, often without direct observation.
As you move from one-off to fully automated, you need stronger safety defaults, predictable output, and better observability. This classification also influences how you design the interface: prompts and interactive confirmations can work for one-off scripts, but are dangerous when the script becomes part of an unattended workflow.
A real-world scenario illustrates the point. A sysadmin writes a quick PowerShell snippet to disable stale AD accounts by reading a CSV exported from HR. It works, so it gets reused each month. Eventually it’s scheduled. The original script relied on Read-Host confirmation and had no logging beyond console output. When it runs on a server without an interactive session, it hangs; when someone “fixes” it by removing prompts, it disables accounts based on an outdated CSV because there is no input validation. A small upfront decision—“this is becoming operational”—would have driven changes in interface, validation, logging, and idempotency.
Define the contract: inputs, outputs, and side effects
Operational scripts should have a clear contract: what inputs they accept, what outputs they produce, and what side effects they cause. This is not just documentation; it is how you prevent accidental misuse and how you make the script composable in automation chains.
Inputs include parameters (flags, named options), environment variables, configuration files, and standard input (stdin). Scripts that silently pull configuration from multiple places are hard to reason about, especially when they behave differently in an interactive shell vs a scheduled task context. Prefer explicit parameters for anything that changes behavior materially, and treat environment variables as optional overrides with clear precedence.
Outputs should be predictable. Decide what goes to stdout vs stderr, and whether the script emits human-readable text, machine-readable formats (JSON/CSV), or both. For scripts that will feed other automation, structured output matters more than pretty formatting.
Side effects are the actual changes you make: creating accounts, rebooting hosts, changing firewall rules, deleting files, or rotating keys. Be explicit about these behaviors in help text and in logging. A common failure mode is a script that “audits” by default but “fixes” when a certain variable is present, without clearly advertising it.
In PowerShell, use advanced functions with CmdletBinding() to formalize the contract. In Bash, use getopts (or a small argument parser) and consistent exit codes.
function Invoke-StaleComputerCleanup {
[CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='High')]
param(
[Parameter(Mandatory=$true)]
[int]$InactiveDays,
[Parameter(Mandatory=$true)]
[string]$SearchBase,
[switch]$DisableOnly,
[ValidateSet('JSON','Text')]
[string]$OutputFormat = 'Text'
)
# Contract notes:
# - Writes structured output when OutputFormat=JSON
# - Uses ShouldProcess for changes
# - Side effects: disables or removes computer accounts
}
The presence of SupportsShouldProcess enables -WhatIf and -Confirm, which is a practical best practice when your script makes changes. It also signals to other engineers that the script is designed with safety in mind.
Use consistent structure and naming conventions
A script that’s readable is easier to review, safer to modify under pressure, and more likely to be reused correctly. Consistency matters more than personal preference; the goal is to reduce cognitive load.
Start by choosing a standard layout. For PowerShell, it’s typically: parameter block, initialization, functions, main logic. For Bash, it’s: strict mode and traps, constants and defaults, functions, argument parsing, main.
Naming conventions should align with the ecosystem. PowerShell benefits from approved verb-noun naming (Get-, Set-, Test-, Invoke-) because it makes intent obvious and improves discoverability. In Bash, function names and variables should be lowercase with underscores or uppercase for constants; the key is to pick a convention and stick to it.
Also aim for small, single-purpose functions. Large scripts become manageable when each function does one thing: parse inputs, validate prerequisites, perform an operation on one target, format output. This is the foundation for testing and for safe refactoring later.
In an ops context, the best “structure” practice is separating business logic from I/O. For example, have a function that computes “which hosts should be patched” separately from the function that prints the list or initiates patching. This separation makes it easier to add -WhatIf, to test the decision logic, and to change output formats without rewriting everything.
Prefer idempotent operations and safe defaults
Idempotency means you can run the script multiple times and get the same end state without unintended side effects. In infrastructure automation, idempotency is one of the most important scripting best practices because it turns a fragile sequence into a repeatable operation.
Safe defaults complement idempotency. Default behavior should avoid destructive changes and avoid ambiguous targeting. A script that deletes resources should require explicit scoping parameters and ideally an explicit “apply” switch.
A common pattern is “discover, plan, apply.” The script first discovers current state, then computes the delta (what would change), then applies changes. Even if you don’t implement a full plan file, you can log the intended changes and support a dry-run mode.
In PowerShell, -WhatIf can provide this behavior if you wrap changes in ShouldProcess. In Bash, implement a --dry-run flag and route change commands through a wrapper function that either executes or prints.
bash
#!/usr/bin/env bash
set -euo pipefail
DRY_RUN=0
run() {
if [[ "$DRY_RUN" -eq 1 ]]; then
echo "[dry-run] $*"
else
"$@"
fi
}
# Example idempotent operation: ensure a directory exists
ensure_dir() {
local dir="$1"
if [[ -d "$dir" ]]; then
return 0
fi
run mkdir -p "$dir"
}
Idempotency also means being careful with “append” operations and with time-based names. If a script appends firewall rules every run, you get rule sprawl. If it creates a new scheduled task with a timestamp name every time, you get duplicates. Prefer “ensure X exists with these properties” over “create X.”
A real-world scenario: a team rotates local admin passwords across Windows endpoints. The first version of the script used net user to set a password but didn’t verify the account existed on all machines and didn’t check whether the password update succeeded. Machines that were offline at run time remained stale. When the script was rerun, it overwrote a subset but not all, and there was no authoritative record. An idempotent approach would record desired state in a central store (or at least log results per host), re-attempt only failed targets, and avoid “half-finished” ambiguity.
Validate prerequisites and environment early
Scripts fail in production for reasons that are obvious in hindsight: missing modules, wrong privileges, incorrect region/subscription, absent network connectivity, or an unexpected OS version. Validating prerequisites upfront prevents partial execution and reduces the blast radius.
Start with explicit checks for what you require: version constraints, module availability, permissions, and reachability. In PowerShell, you can check $PSVersionTable.PSVersion and Get-Module -ListAvailable. In Bash, check commands with command -v.
Fail fast with clear error messages. “Access denied” is not enough; say what privilege is required and how to satisfy it. If the script requires elevation, detect it and stop before making partial changes.
powershell
# Require PowerShell 7+ for certain features
if ($PSVersionTable.PSVersion.Major -lt 7) {
throw "This script requires PowerShell 7+. Current: $($PSVersionTable.PSVersion)"
}
# Verify module
if (-not (Get-Module -ListAvailable -Name Az.Accounts)) {
throw "Required module Az.Accounts not found. Install-Module Az -Scope AllUsers"
}
Prerequisite checks are also where you enforce the “right environment.” If a script is intended for non-production by default, require an explicit -Environment Production parameter to proceed in prod, and validate that parameter against known values.
For cloud automation, validate identity context. Many incidents come from running az or aws commands in the wrong subscription/account because the CLI context persisted from a previous task.
bash
# Azure CLI example: assert subscription
EXPECTED_SUB="00000000-0000-0000-0000-000000000000"
CURRENT_SUB=$(az account show --query id -o tsv)
if [[ "$CURRENT_SUB" != "$EXPECTED_SUB" ]]; then
echo "Wrong Azure subscription. Expected $EXPECTED_SUB, got $CURRENT_SUB" >&2
exit 2
fi
This kind of check may feel “paranoid,” but it is cheap insurance, especially for scripts that can delete or modify infrastructure.
Make error handling deliberate, not incidental
Error handling is where scripts most often diverge from reliable automation. Default behaviors differ across shells and languages, and relying on defaults leads to either overly brittle scripts or scripts that silently ignore failures.
In Bash, set -e (or set -euo pipefail) is a starting point, but it is not a complete strategy. It changes behavior in subtle ways around conditionals and pipelines, and you still need to handle expected non-zero exit codes intentionally. When a command can fail in an acceptable way (for example, “resource not found” during a cleanup), handle that case explicitly.
In PowerShell, distinguish between terminating and non-terminating errors. Many cmdlets emit non-terminating errors unless you set -ErrorAction Stop or configure $ErrorActionPreference. For operational scripts, you usually want failures to be visible and to stop the run unless you have a controlled retry or fallback.
powershell
$ErrorActionPreference = 'Stop'
try {
Get-ADUser -Identity 'doesnotexist' | Out-Null
} catch {
Write-Error "Lookup failed: $($_.Exception.Message)"
exit 1
}
Also standardize exit codes. In mixed environments, other tools (schedulers, monitoring systems, CI jobs) decide success/failure based on exit status. A script that prints “ERROR” but exits 0 will be treated as healthy.
Where it fits, implement retries with backoff for transient failures (network timeouts, API rate limits). Be careful not to retry non-transient failures (auth, invalid input) because that increases load and delays feedback.
bash
retry() {
local -r max_attempts="$1"; shift
local -r delay="$1"; shift
local attempt=1
until "$@"; do
if (( attempt >= max_attempts )); then
return 1
fi
sleep "$delay"
attempt=$((attempt+1))
done
}
# Example: retry an API call
retry 5 2 curl -fsS https://internal-api.example.net/health
The key best practice is to make error behavior explicit: what is fatal, what is retried, what is skipped, and how those outcomes are reported.
Build observability in: logging, metrics, and traceable output
When scripts run unattended, observability is the only way to understand what happened. Good logging is not verbose output; it’s structured, contextual information that lets you answer: what ran, against which targets, with what inputs, what changed, and what failed.
Start with a consistent log format that includes timestamps, severity, and correlation identifiers. A correlation identifier can be as simple as a generated run ID printed at start and included in every log line. That run ID becomes critical when you’re correlating script actions with system events.
In PowerShell, you can use Start-Transcript for capture, but transcripts are not a substitute for structured logs. Prefer writing explicit log lines and optionally emitting JSON when the logs will be ingested.
powershell
$RunId = [guid]::NewGuid().ToString()
function Write-Log {
param(
[ValidateSet('INFO','WARN','ERROR')][string]$Level,
[string]$Message,
[hashtable]$Data
)
$entry = [ordered]@{
ts = (Get-Date).ToString('o')
level = $Level
runId = $RunId
msg = $Message
data = $Data
}
$entry | ConvertTo-Json -Compress
}
Write-Log -Level INFO -Message "Starting cleanup" -Data @{host=$env:COMPUTERNAME}
In Bash, logging functions help keep output consistent and allow easy redirection.
bash
log() {
local level="$1"; shift
printf '%s level=%s msg=%q\n' "$(date -Is)" "$level" "$*" >&2
}
log INFO "starting patch scan" "run_id=$RUN_ID"
As scripts mature, metrics become valuable: number of targets processed, success/failure counts, duration per phase. You may not have a metrics system for every script, but even writing a final structured “run result” line enables later parsing.
A practical scenario: an organization automates certificate renewal with a script that pushes new certs to load balancers and restarts services. Early runs “worked,” but when a renewal failed, the only record was “failed” in the scheduler history. Adding structured logs (which cert thumbprint was deployed where, which restart commands ran, and which health checks passed) turned future issues from guesswork into a quick verification step.
Handle secrets safely (and assume your script will be copied)
Secrets management is non-negotiable. Scripts get emailed, pasted into tickets, stored in wikis, and copied across servers. Hard-coded credentials or tokens will leak.
Adopt a hierarchy of preferred secret sources. In many environments, the best option is a managed identity (cloud) or Kerberos/AD-integrated authentication (on-prem) where no secret is present. If that’s not available, prefer a secrets manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault). If you must use environment variables, treat them as sensitive and ensure logs never print them. Avoid plaintext config files unless they are encrypted and access-controlled.
In PowerShell, use Get-Credential for interactive prompts, but don’t use it for unattended runs. For unattended, integrate with a vault or use certificate-based auth where supported.
powershell
# Azure example: retrieve a secret from Key Vault (requires Az modules and access)
$secret = Get-AzKeyVaultSecret -VaultName "kv-prod-ops" -Name "SqlAdminPassword"
$sqlPassword = $secret.SecretValueText
In Bash, avoid set -x in scripts that may handle secrets, because it can echo commands and variables. If you need debugging, implement selective debug logging that redacts sensitive fields.
Also treat output as sensitive. Many scripts accidentally log full connection strings, bearer tokens, or headers. A best practice is to centralize logging and apply redaction there.
bash
redact() {
sed -E 's/(Authorization: Bearer )[A-Za-z0-9._-]+/\1REDACTED/g'
}
curl -sS -H "Authorization: Bearer $TOKEN" https://api.example.net/data \
| redact
The operational mindset is: assume the script will be run in places you didn’t anticipate and read by people who weren’t part of its creation. Secure defaults reduce the chance of accidental exposure.
Design for least privilege and explicit authorization
A script that runs as Domain Admin because “it’s easier” is a security incident waiting to happen. The best practice is to identify the minimal permissions required and enforce that operationally.
In practice, this means creating dedicated service accounts (or managed identities) with scoped permissions, and designing the script so it doesn’t assume full rights. It also means separating read-only discovery actions from write actions; many scripts can gather necessary information with low privileges and only elevate for the final apply stage.
Explicit authorization also includes change control. For high-impact actions, require explicit flags such as --apply or -Force, and consider integrating a simple approval step in pipelines rather than interactive prompts in the script itself. In CI/CD systems, you can gate execution with approvals, while the script remains non-interactive and deterministic.
If your script operates across tenants/subscriptions/regions, require explicit selection parameters and validate them. Accidental cross-environment changes are common when credentials have broad reach.
Be careful with concurrency and shared state
As automation scales, scripts are often run concurrently: multiple pipeline jobs, multiple scheduled tasks, or multiple operators. Concurrency issues show up as race conditions, duplicate work, or corrupted state.
The first step is to avoid shared mutable state where possible. If the script writes to a fixed file path, ensure it uses per-run directories or unique filenames (including run IDs). If it updates shared resources (a DNS record, a load balancer pool), implement locking or at least detection of concurrent runs.
On Linux, file locks via flock are a practical control. On Windows, you can use a mutex via .NET from PowerShell or a lock file with proper semantics.
bash
# Prevent concurrent runs
exec 200>/var/lock/myjob.lock
flock -n 200 || { echo "Another instance is running" >&2; exit 3; }
Concurrency also affects API usage. If you parallelize calls for speed, watch for rate limits and consider bounded concurrency rather than “firehose” parallelism. In PowerShell 7, ForEach-Object -Parallel is convenient but can overwhelm endpoints if not throttled.
powershell
$targets | ForEach-Object -Parallel {
# do work
} -ThrottleLimit 10
The best practice is not “never parallelize,” but “parallelize intentionally,” with throttling and with output that remains traceable per target.
Make scripts maintainable: modularity, reuse, and dependencies
Maintainability is not an abstract concern; it directly affects incident response and operational continuity. When a script breaks during a critical window, you want small, understandable units you can fix quickly.
Prefer modular design. In PowerShell, consider packaging shared functions into a module (.psm1) rather than copy-pasting between scripts. In Bash, you can source shared libraries, but be mindful of path and versioning issues.
Dependency management is also part of maintainability. If your script relies on external tools (jq, az, kubectl) or specific module versions, document and enforce those dependencies. For PowerShell modules, pin versions where reproducibility matters, especially in build agents.
powershell
# Example: ensure a module version is available
$required = [version]'2.12.1'
$mod = Get-Module -ListAvailable Az.Accounts | Sort-Object Version -Descending | Select-Object -First 1
if (-not $mod -or $mod.Version -lt $required) {
throw "Az.Accounts >= $required is required. Found: $($mod.Version)"
}
The broader best practice here is to treat dependencies as part of the script’s contract. If you can’t guarantee them, vendor the dependency (where appropriate), containerize the runtime, or run in a controlled automation environment.
Write for operators: help text, examples, and guardrails
Operational scripts should be usable by someone other than the author. This is a core scripting best practice: write the script as if you will not be available when it’s run.
In PowerShell, comment-based help (.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE) is easy to generate and shows up in Get-Help. In Bash, a --help output that includes common usage patterns and warnings is often enough.
Guardrails matter because operator mistakes are predictable. If a script accepts a list of hosts, validate the input, reject empty lists, and show a clear preview of targets. If the script supports wildcard selection, require an explicit acknowledgement when the wildcard expands beyond a threshold.
bash
usage() {
cat <<'EOF'
Usage:
rotate-logs.sh --path /var/log/myapp --keep-days 14 [--dry-run]
Notes:
--path must be a directory.
--dry-run prints actions without deleting.
EOF
}
When you combine help text with safe defaults and idempotent behavior, you reduce both accidental misuse and the need for tribal knowledge.
Manage data carefully: parsing, encoding, and time
Automation scripts often fail at the boundaries: reading CSVs with unexpected delimiters, parsing command output that changes between versions, handling Unicode paths, or comparing times across time zones.
Prefer machine-readable formats over scraping human output. If a tool can output JSON, use it. For example, az and kubectl can output JSON, and PowerShell naturally handles objects.
In Bash, JSON parsing should be done with a parser like jq rather than grep/awk on JSON strings. In PowerShell, avoid converting objects to strings too early; keep objects as objects until the final output stage.
Time handling is another common source of subtle bugs. Decide whether to use UTC or local time. In distributed systems, UTC is usually safer. Be explicit when converting.
powershell
# Use UTC timestamps for comparisons
$cutoff = (Get-Date).ToUniversalTime().AddDays(-30)
If you generate filenames with timestamps, choose a sortable format like ISO 8601 (and avoid characters invalid on Windows).
Implement change safety: dry runs, confirmation, and rollback thinking
Even with idempotency, many scripts still perform changes that can’t be trivially undone. Good scripting best practices include making those changes safer to apply.
Dry runs are the first layer. They let you validate targeting and see planned actions. In PowerShell, -WhatIf is a natural approach; in other shells, implement --dry-run.
Confirmation is the second layer. For manual execution, -Confirm can be appropriate, but don’t embed interactive prompts into scripts that might later be scheduled. Instead, separate “plan” and “apply” into distinct modes. A pipeline can run “plan” automatically and require approval for “apply.”
Rollback is the third layer, and it often means “design so rollback is possible,” not necessarily “implement a full undo.” For example, when you edit configuration files, take a backup first and write changes atomically. When you update a load balancer pool, keep the previous state recorded.
Atomic writes matter on both Windows and Linux. In Bash, write to a temp file and move it into place. In PowerShell, similar logic applies: write to a new file and then replace.
bash
tmp=$(mktemp)
render_config > "$tmp"
chmod 0644 "$tmp"
mv "$tmp" /etc/myapp/config.conf
A real-world scenario: a script updates Nginx upstreams based on service discovery. The naive version edits /etc/nginx/nginx.conf in place and reloads. One malformed entry corrupts the file and the reload fails, leaving the service in a broken state. A safer approach writes a generated file under conf.d/, validates with nginx -t, and only then reloads. This isn’t just “better engineering”; it’s the difference between a minor automation bug and an outage.
Treat configuration as data, not code
Hard-coding environment-specific details (server names, paths, thresholds) is an anti-pattern that makes scripts brittle and encourages risky edits. A better best practice is to externalize configuration into data files and keep the script’s logic generic.
Choose a configuration format that fits your tooling. For PowerShell, JSON is common; YAML is also used but requires a parser module. For Bash, simple .env-style key/value files can work, but be careful about sourcing untrusted files because it executes code.
Separate “defaults” from “overrides.” The script can provide safe defaults, while environment-specific config files define differences. This also makes code review easier: changes to configuration are visible and don’t require reading logic diffs.
json
{
"environment": "prod",
"inactiveDays": 90,
"searchBase": "OU=Computers,DC=example,DC=com",
"disableOnly": true
}
In PowerShell, you can load this and validate it before use.
powershell
$config = Get-Content .\config.json -Raw | ConvertFrom-Json
if ($config.environment -notin @('dev','test','prod')) { throw "Invalid environment" }
Configuration as data also helps you run the same script across multiple environments consistently, which is a prerequisite for reliable automation.
Use version control and code review as operational controls
Version control (typically Git) is not only for developers. For ops scripts, it is the system of record for what runs in production. It enables rollback, auditing, collaboration, and reproducibility.
A practical best practice is to store scripts in a repository with a clear structure: scripts/ for entry points, modules/ or lib/ for shared code, config/ for environment files, and docs/ for usage notes. Add a README that explains the intent, prerequisites, and how to run safely.
Code review is a safety control. Many scripting incidents are prevented when a second engineer spots a dangerous default, a wildcard that matches too much, or a missing environment check. Reviews also spread knowledge so scripts are not “owned” by a single person.
If you can’t do formal pull requests for every script, at least adopt lightweight review for scripts that touch production state or credentials. The classification discussed earlier helps: one-off scripts may not need a PR; operator-run and fully automated scripts generally should.
Add testing where it pays off (and keep it realistic)
Testing in scripting doesn’t have to mean building a full test suite for every utility. The best practice is to add tests where they reduce risk in high-change or high-impact areas.
For PowerShell, Pester is the standard testing framework. You can unit test pure functions (like “parse this config and decide targets”) and integration test with mocks. For Bash, you can use lightweight tests with bats or simple harness scripts.
Even without a test framework, you can build “self-checks” into the script: validate input formats, validate that generated configs pass syntax checks (nginx -t, sshd -t, terraform validate), or validate that API responses meet expectations.
A useful pattern is to create a “validation mode” that does everything except apply changes. This is similar to dry-run but focused on verifying that the environment, dependencies, and generated artifacts are correct. That validation mode can be run in CI on every commit.
Another realistic testing layer is running scripts in disposable environments: containers, ephemeral VMs, or a dedicated test OU/subscription. For system scripts, this is often more valuable than pure unit tests because it catches environmental assumptions.
Automate delivery: packaging, signing, and controlled execution
Once scripts become operational, how you deliver and execute them matters. Copying a script via SMB to “that one server” is not a sustainable deployment strategy.
PowerShell environments often benefit from code signing. Signing scripts and enforcing an execution policy (where appropriate) reduces the risk of tampering and makes provenance clearer. Be aware that execution policy is not a security boundary on its own, but in enterprise settings it can support operational controls.
Packaging is another approach. Instead of distributing loose scripts, ship a module with versioned releases. For cross-platform automation, containers can provide a consistent runtime that includes the right CLI versions and dependencies.
Controlled execution means having a known runner: a scheduled task with a defined service account, an automation account, a CI runner, or a job orchestrator. The runner should define the environment (PATH, module paths, network access) to reduce “works on my machine” failures.
Where you use CI/CD for script changes, include a pipeline that runs linting (format checks), validation mode, and perhaps a canary run in a non-prod environment. This pipeline approach ties back to earlier best practices: explicit contracts, prerequisites, and deterministic behavior make automation-friendly delivery possible.
Use linting and formatting to prevent subtle bugs
Linting catches mistakes that are easy to miss in review: unused variables, unsafe quoting, ambiguous globbing, and inconsistent error handling.
For PowerShell, PSScriptAnalyzer is commonly used and integrates with CI. For Bash, shellcheck is extremely valuable; it catches quoting issues that can turn a safe script into a destructive one. Enforcing formatting (like consistent indentation) reduces noise in diffs and helps reviewers focus on logic.
Even if you don’t run lint tools everywhere, using them before committing changes is a strong best practice. Many operational incidents are rooted in trivial errors: an unquoted variable that expands to multiple paths, or a conditional that always evaluates true.
Here is a simple example of why quoting matters in Bash:
bash
# Dangerous if $path contains spaces or globs
rm -rf $path
# Safer
rm -rf -- "$path"
Likewise in PowerShell, prefer parameterized cmdlets over string-built commands whenever possible. It improves safety and reduces injection risk.
Avoid shell injection and unsafe command construction
Shell injection is not only a web application concern. Ops scripts frequently accept hostnames, file paths, or identifiers from CSVs, tickets, or API responses. If you build command lines via string concatenation, you risk executing unintended commands.
In Bash, avoid eval. Pass arguments as arrays and quote variables. Validate inputs against expected patterns (for example, hostnames) before using them in commands.
In PowerShell, avoid building strings that are then executed with Invoke-Expression. Prefer calling cmdlets directly with parameters, or use Start-Process with -ArgumentList when you must invoke external executables.
powershell
# Prefer this
Start-Process -FilePath "ping" -ArgumentList @('-n','1',$host) -NoNewWindow -Wait
# Avoid this
Invoke-Expression "ping -n 1 $host"
Input validation is not about distrusting colleagues; it’s about preventing mistakes and reducing the impact of unexpected data.
Plan for scale: targeting, batching, and timeouts
Scripts that work fine on 10 servers can fall apart on 1,000. Scaling requires you to think about batching, timeouts, and partial failure handling.
Targeting should be explicit and reviewable. If you select targets by querying AD, CMDB, or cloud tags, log the selection criteria and the final count. If the count exceeds a threshold, require confirmation or refuse to run unless an override is provided.
Batching helps with both performance and safety. For operations like patching or restarts, you often want to process in waves to maintain service availability. A script should support batch sizes or concurrency limits and should record progress so it can resume after a failure.
Timeouts are critical when calling remote endpoints. Without timeouts, a script can hang indefinitely and block subsequent runs. Most CLIs and HTTP clients support timeouts; set them deliberately.
Partial failure handling is where you need to be honest about what “success” means. If a script processes 500 targets and 5 fail, should it exit non-zero? Often yes, but you may also want it to continue processing and report failures at the end. The best practice is to choose a strategy aligned with how the script is consumed. If a pipeline expects “all-or-nothing,” fail fast; if operations can tolerate partial completion, continue and produce a machine-readable report.
Document operational context: runbooks, ownership, and deprecation
Scripts don’t exist in isolation; they exist in an operational ecosystem. Documenting that context is part of scripting best practices because it reduces the risk of misuse and abandonment.
At minimum, document who owns the script, what systems it touches, and how it is intended to be run (manual vs scheduled). Include references to any runbooks, maintenance windows, or change control processes that apply.
Deprecation is also worth addressing. Scripts get replaced, but old versions linger on jump boxes and file shares. If a script is superseded, mark it clearly, and ideally make it refuse to run unless a --force-legacy flag is provided. It’s better to be slightly annoying than to have operators unknowingly run the wrong tool.
This operational documentation ties back to the contract idea earlier: clarity about scope and side effects isn’t just for readability; it is a control mechanism.
Real-world example: automating group membership safely (PowerShell)
Consider a common task: ensuring a set of users are members of an AD group based on an authoritative list (for example, a CSV from HR or an access request system). The naive approach is to loop through the list and call Add-ADGroupMember. That “works,” but it can also generate errors for existing members, and it rarely produces a clear report.
A better pattern follows the practices covered so far: validate inputs, compute a delta (idempotency), support -WhatIf, log actions, and produce structured output.
powershell
function Sync-AdGroupMembers {
[CmdletBinding(SupportsShouldProcess=$true)]
param(
[Parameter(Mandatory=$true)][string]$Group,
[Parameter(Mandatory=$true)][string]$CsvPath
)
$ErrorActionPreference = 'Stop'
if (-not (Test-Path $CsvPath)) {
throw "CSV not found: $CsvPath"
}
$desired = Import-Csv $CsvPath | ForEach-Object { $_.SamAccountName } | Where-Object { $_ } | Sort-Object -Unique
if (-not $desired -or $desired.Count -eq 0) {
throw "CSV contained no SamAccountName values. Refusing to proceed."
}
$current = Get-ADGroupMember -Identity $Group -Recursive | Where-Object objectClass -eq 'user' |
ForEach-Object { $_.SamAccountName } | Sort-Object -Unique
$toAdd = Compare-Object -ReferenceObject $current -DifferenceObject $desired -PassThru | Where-Object { $_ -in $desired }
$toRemove = Compare-Object -ReferenceObject $current -DifferenceObject $desired -PassThru | Where-Object { $_ -in $current }
foreach ($u in $toAdd) {
if ($PSCmdlet.ShouldProcess("$Group", "Add $u")) {
Add-ADGroupMember -Identity $Group -Members $u
}
}
foreach ($u in $toRemove) {
if ($PSCmdlet.ShouldProcess("$Group", "Remove $u")) {
Remove-ADGroupMember -Identity $Group -Members $u -Confirm:$false
}
}
[pscustomobject]@{
group = $Group
desiredCount = $desired.Count
currentCount = $current.Count
added = @($toAdd)
removed = @($toRemove)
}
}
This design is safer because it doesn’t blindly “add everything” and it won’t silently proceed with an empty CSV. It also produces an object that can be converted to JSON and stored for audit. If you later schedule this, you can run it with -WhatIf in CI to validate the delta without applying changes.
Real-world example: log rotation with atomic operations (Bash)
Log rotation is often handled by system tools, but environments sometimes have application-specific logs in unusual locations or formats. A script that deletes files based on patterns is deceptively risky.
Applying best practices here means: explicit targeting, validation, dry-run mode, safe quoting, and predictable output. It also means being careful with time calculations and ensuring that the script doesn’t delete too broadly.
bash
#!/usr/bin/env bash
set -euo pipefail
DRY_RUN=0
PATH_TO_ROTATE=""
KEEP_DAYS=14
run() {
if [[ "$DRY_RUN" -eq 1 ]]; then
echo "[dry-run] $*" >&2
else
"$@"
fi
}
while [[ $# -gt 0 ]]; do
case "$1" in
--path) PATH_TO_ROTATE="$2"; shift 2 ;;
--keep-days) KEEP_DAYS="$2"; shift 2 ;;
--dry-run) DRY_RUN=1; shift ;;
--help) echo "Usage: $0 --path DIR [--keep-days N] [--dry-run]"; exit 0 ;;
*) echo "Unknown arg: $1" >&2; exit 2 ;;
esac
done
if [[ -z "$PATH_TO_ROTATE" ]]; then
echo "--path is required" >&2
exit 2
fi
if [[ ! -d "$PATH_TO_ROTATE" ]]; then
echo "Path is not a directory: $PATH_TO_ROTATE" >&2
exit 2
fi
# Find and delete files older than KEEP_DAYS
# -print0 avoids issues with spaces/newlines
while IFS= read -r -d '' f; do
run rm -f -- "$f"
done < <(find "$PATH_TO_ROTATE" -type f -mtime "+$KEEP_DAYS" -name '*.log' -print0)
This is intentionally conservative: it requires --path, uses -name '*.log' to avoid deleting arbitrary files, and uses -print0 to handle filenames safely. In practice, you might extend it with logging and a summary of deleted files, but the important best practice is that deletion logic is explicit and controlled.
Real-world example: preventing “wrong subscription” cloud changes (Azure CLI)
Cloud automation often fails not because commands are wrong, but because they run in the wrong context. A script that creates resources in the wrong subscription is a classic, expensive error.
Here’s a minimal pattern that reflects several best practices: explicit contract, prerequisite checks, environment validation, and safe defaults.
bash
#!/usr/bin/env bash
set -euo pipefail
EXPECTED_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000"
RESOURCE_GROUP="rg-ops-automation"
LOCATION="eastus"
command -v az >/dev/null || { echo "Azure CLI (az) is required" >&2; exit 127; }
CURRENT_SUB=$(az account show --query id -o tsv)
if [[ "$CURRENT_SUB" != "$EXPECTED_SUBSCRIPTION_ID" ]]; then
echo "Refusing to run in subscription $CURRENT_SUB (expected $EXPECTED_SUBSCRIPTION_ID)" >&2
exit 2
fi
# Idempotent: create RG only if missing
if ! az group show -n "$RESOURCE_GROUP" >/dev/null 2>&1; then
az group create -n "$RESOURCE_GROUP" -l "$LOCATION" >/dev/null
fi
echo "Resource group is present: $RESOURCE_GROUP"
This example is deliberately small, but it demonstrates the habit: don’t rely on ambient context when the stakes are high. If you later build on this to create network rules, storage accounts, or identities, the subscription check remains a critical guardrail.
Standardize exit codes and machine-readable results
As scripts become inputs to other systems, exit codes and result output become part of your automation API.
Adopt a simple policy. Exit 0 for success, non-zero for failure, and use distinct exit codes for different failure classes if it helps operators (for example, 2 for invalid arguments, 3 for lock contention, 4 for failed prerequisites). Don’t overcomplicate it, but avoid returning 0 when there were significant failures.
For machine-readable results, JSON is often the most portable choice. Even if you mostly write human logs, consider emitting a final JSON line that summarizes outcome.
json
{"runId":"...","status":"partial_failure","processed":500,"failed":5,"durationSeconds":312}
If you adopt this consistently across scripts, you can build generic monitoring around it. This is a compounding benefit: one well-chosen convention improves operability across your entire automation estate.
Balance portability with platform conventions
IT teams often maintain a mix of Windows and Linux automation. Portability is desirable, but it should not come at the cost of fighting platform conventions.
A practical best practice is to use the native tool where it’s strongest. PowerShell excels at Windows management and object pipelines; Bash excels at gluing Unix tools together. Python is often useful when you need cross-platform libraries, complex data handling, or robust HTTP interactions.
If you require cross-platform behavior, PowerShell 7 is a strong option, but be mindful that not all Windows-only modules work cross-platform. Conversely, Bash scripts that assume GNU utilities may fail on macOS or minimal containers.
Where portability matters, document supported platforms explicitly and validate at runtime. It is better to refuse to run than to run incorrectly.
Put it all together: a practical checklist you can enforce
By this point, the patterns should feel connected: explicit contracts enable safe defaults; safe defaults rely on validation; validation and deliberate error handling make logging meaningful; logging and structured output make automation observable; and version control plus testing makes changes safer.
A pragmatic way to operationalize scripting best practices is to adopt a small set of enforceable rules for scripts that touch production. For example: every operational script must accept explicit environment selection, must support dry-run or -WhatIf for change operations, must log a run ID, must validate prerequisites and target counts, must not embed secrets, and must be stored in a repository with peer review.
The point is not bureaucracy; it’s to make reliability the default outcome. As your automation footprint grows, these practices turn scripts from fragile personal tools into dependable operational assets.