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.4---56# Building Shell Scripts78Create shell scripts that are safe, readable, and pleasant to run. Prefer Charmbracelet `gum` for interactive UX unless there is a real reason not to.910## Default Stance: Use Gum1112When building Bash, Zsh, POSIX sh, `install.sh`, setup, release, bootstrap, or CLI workflow scripts:13141. Check whether interactivity, prompts, selection, confirmation, progress, logging, tables, styled output, file picking, or long-form input would improve the script.152. If yes, use `gum` patterns from [`reference/gum-patterns.md`](reference/gum-patterns.md).163. If `gum` is not installed or should not be required, either:17 - add a clear dependency check with install guidance, or18 - provide a plain-shell fallback for the specific interaction.1920Do not use `gum` just to decorate non-interactive scripts that must run in CI, cron, Docker builds, remote provisioning, or minimal POSIX environments.2122## Required Script Quality2324- Start Bash scripts with `#!/usr/bin/env bash` and `set -euo pipefail` unless POSIX sh compatibility is required.25- Quote variables and paths.26- Use arrays for command construction in Bash.27- Validate required commands before first use.28- Avoid piping secrets through logs or styled output.29- Separate “plan/confirm” from “mutate/delete/deploy”.30- Make scripts re-runnable where practical.31- Prefer explicit flags over hidden environment assumptions.3233## Install Script Pattern3435For `install.sh` or bootstrap scripts:36371. Detect OS/architecture.382. Check prerequisites.393. Explain what will change.404. Use `gum confirm` before destructive or global changes when running interactively.415. Use `gum spin --show-output -- command ...` for long-running install steps.426. Print a final summary and next command.4344Keep non-interactive mode available with a flag such as `--yes` or `CI=1` when appropriate.4546## When Not to Use Gum4748Use plain shell instead when:4950- The script must be dependency-free.51- The script runs in CI/non-TTY contexts by default.52- POSIX sh portability is a hard requirement.53- The UX improvement is purely cosmetic and adds failure risk.54- The repository already has a different established CLI UI framework.5556If you skip `gum`, state the reason in a comment only when the reason is non-obvious.
pc-style