Building Shell Scripts
Create shell scripts that are safe, readable, and pleasant to run. Prefer Charmbracelet gum for interactive UX unless there is a real reason not to.
Default Stance: Use Gum
When building Bash, Zsh, POSIX sh, install.sh, setup, release, bootstrap, or CLI workflow scripts:
- Check whether interactivity, prompts, selection, confirmation, progress, logging, tables, styled output, file picking, or long-form input would improve the script.
- If yes, use
gum patterns from reference/gum-patterns.md.
- If
gum is not installed or should not be required, either:
- add a clear dependency check with install guidance, or
- provide a plain-shell fallback for the specific interaction.
Do not use gum just to decorate non-interactive scripts that must run in CI, cron, Docker builds, remote provisioning, or minimal POSIX environments.
Required Script Quality
- Start Bash scripts with
#!/usr/bin/env bash and set -euo pipefail unless POSIX sh compatibility is required.
- Quote variables and paths.
- Use arrays for command construction in Bash.
- Validate required commands before first use.
- Avoid piping secrets through logs or styled output.
- Separate “plan/confirm” from “mutate/delete/deploy”.
- Make scripts re-runnable where practical.
- Prefer explicit flags over hidden environment assumptions.
Install Script Pattern
For install.sh or bootstrap scripts:
- Detect OS/architecture.
- Check prerequisites.
- Explain what will change.
- Use
gum confirm before destructive or global changes when running interactively.
- Use
gum spin --show-output -- command ... for long-running install steps.
- Print a final summary and next command.
Keep non-interactive mode available with a flag such as --yes or CI=1 when appropriate.
When Not to Use Gum
Use plain shell instead when:
- The script must be dependency-free.
- The script runs in CI/non-TTY contexts by default.
- POSIX sh portability is a hard requirement.
- The UX improvement is purely cosmetic and adds failure risk.
- The repository already has a different established CLI UI framework.
If you skip gum, state the reason in a comment only when the reason is non-obvious.
1---2name: building-shell-scripts3description: "Builds polished, user-friendly shell scripts and install.sh flows. Use when creating or editing Bash, Zsh, POSIX sh, setup scripts, installer scripts, CLI workflows, or interactive terminal automation; prefers Charmbracelet gum unless there is a concrete reason not to."4metadata:5 source: https://skillmd.com/skills/pc-style/building-shell-scripts6---78# Building Shell Scripts910Create shell scripts that are safe, readable, and pleasant to run. Prefer Charmbracelet `gum` for interactive UX unless there is a real reason not to.1112## Default Stance: Use Gum1314When building Bash, Zsh, POSIX sh, `install.sh`, setup, release, bootstrap, or CLI workflow scripts:15161. Check whether interactivity, prompts, selection, confirmation, progress, logging, tables, styled output, file picking, or long-form input would improve the script.172. If yes, use `gum` patterns from [`reference/gum-patterns.md`](reference/gum-patterns.md).183. If `gum` is not installed or should not be required, either:19 - add a clear dependency check with install guidance, or20 - provide a plain-shell fallback for the specific interaction.2122Do not use `gum` just to decorate non-interactive scripts that must run in CI, cron, Docker builds, remote provisioning, or minimal POSIX environments.2324## Required Script Quality2526- Start Bash scripts with `#!/usr/bin/env bash` and `set -euo pipefail` unless POSIX sh compatibility is required.27- Quote variables and paths.28- Use arrays for command construction in Bash.29- Validate required commands before first use.30- Avoid piping secrets through logs or styled output.31- Separate “plan/confirm” from “mutate/delete/deploy”.32- Make scripts re-runnable where practical.33- Prefer explicit flags over hidden environment assumptions.3435## Install Script Pattern3637For `install.sh` or bootstrap scripts:38391. Detect OS/architecture.402. Check prerequisites.413. Explain what will change.424. Use `gum confirm` before destructive or global changes when running interactively.435. Use `gum spin --show-output -- command ...` for long-running install steps.446. Print a final summary and next command.4546Keep non-interactive mode available with a flag such as `--yes` or `CI=1` when appropriate.4748## When Not to Use Gum4950Use plain shell instead when:5152- The script must be dependency-free.53- The script runs in CI/non-TTY contexts by default.54- POSIX sh portability is a hard requirement.55- The UX improvement is purely cosmetic and adds failure risk.56- The repository already has a different established CLI UI framework.5758If you skip `gum`, state the reason in a comment only when the reason is non-obvious.