shell-scripting

Shell & CLI Scripting

A script is a contract: given inputs, do exactly one job, report a precise result, fail loud on anything unexpected. A script that hardcodes a path, swallows errors, or prints a paragraph the caller must parse is a liability — it breaks silently in the next environment and taxes every agent that runs it. This skill makes "robust, data-driven, observable" the default shape.

Scaffold a compliant script instead of hand-writing the boilerplate: python3 scripts/new_script.py --lang bash --name deploy --root . Lint an existing one against the discipline: bash scripts/lint_script.sh path/to/script.sh

The seven non-negotiables

Every script — Bash or Python — satisfies all seven. The checklist in assets/script-checklist.md is the ship gate.

1. Runtime arguments, never hardcoded. Inputs come from flags with sane defaults. No literal machine paths, no baked-in hostnames, no magic constants buried in the body.
2. Fail-closed. Any unmet precondition or sub-command failure stops the script with a non-zero exit and a message — never continue on error.
3. Idempotent. Re-running is safe: detect already-done state, refuse to clobber (or require --force).
4. Observable. Progress to stderr for anything slow; a final, parseable result (one line or --json) on stdout.
5. Precise output. stdout is the result a caller consumes; stderr is narration. Never mix them.
6. Algorithmically honest. No O(n²) where a set/index is O(n). Stream large inputs; bound memory. State complexity when non-obvious.
7. Documented header. PURPOSE / INPUT / OUTPUT / DEPENDENCIES / NOTES at the top — the contract in five lines.

Bash — the robust preamble (copy, don't retype)

#!/usr/bin/env bash
# deploy.sh — PURPOSE: ... / INPUT: ... / OUTPUT: ... / DEPS: ... / NOTES: ...
set -euo pipefail          # -e exit on error · -u unset var is error · -o pipefail catch piped failures
IFS=$'\n\t'                # safe word-splitting (no space-splitting surprises)

cleanup() { rm -f "${_tmp:-}"; }
trap cleanup EXIT          # run on ANY exit path — success, error, or signal