charmed-gum
Write interactive shell scripts with the gum CLI (Charm, charmbracelet): choose, filter, confirm, input, write, file, spin, table, pager, style, join, format, and log, with their flags, exit codes, environment variable defaults, and Bash examples. Use when a Bash or shell script needs a prompt, menu, picker, fuzzy finder, yes or no question, text input, spinner, CSV table, pager, styled output with borders and terminal colors, rendered Markdown, or log lines, without writing Go. Not for Go programs (charmed-huh, charmed-bubbletea).
tpscloud · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tpscloud/charmedimsure --skill charmed-gum技能说明
name: charmed-gum description: "Write interactive shell scripts with the gum CLI (Charm, charmbracelet): choose, filter, confirm, input, write, file, spin, table, pager, style, join, format, and log, with their flags, exit codes, environment variable defaults, and Bash examples. Use when a Bash or shell script needs a prompt, menu, picker, fuzzy finder, yes or no question, text input, spinner, CSV table, pager, styled output with borders and terminal colors, rendered Markdown, or log lines, without writing Go. Not for Go programs (charmed-huh, charmed-bubbletea)." license: "MIT"
gum
Add prompts, pickers, spinners, tables, and styled output to Bash scripts with the gum CLI, with exact flags, keys, and exit codes so scripts handle cancellation correctly.
Written from gum 2.0.2 (its source, gum --help, and each subcommand's help),
the baseline for this skill; run gum --version first (2.x prints
gum version 2.0.2) and confirm a flag with gum <cmd> --help on the
installed version before relying on it.
If the request names a subcommand, go straight to it. Full flags and keys for every subcommand are in references/commands.md.
Workflow
- Check the installed version with
gum --version, or guard the script withgum version-check '>=2.0.0' || exit 1, which exits 1 outside the range. - Pick the command:
choosefor a short list,filterpast a couple dozen items,confirmfor yes/no,inputorwritefor text,filefor a path,spinaround a slow command,style,join,format,table,pager, orlogfor output. - Capture the result with
$(...)and chain|| exit 1so an abort stops the script; then check for an empty result where the command allows one. - Run
bash -n script.shto catch syntax errors before running it. - Run the script in a terminal and exercise the edges: Ctrl+c, Esc, a declined confirm, and an empty selection. If a prompt does not show or a value is wrong, check the rules in How gum behaves and the command's section in references/commands.md.
How gum behaves
- Prompts draw on stderr; the result goes to stdout. Capture with
$(...)and the UI still shows. - Ctrl+c aborts with exit status 130, and Esc aborts with a nonzero status in
every prompt except
table(infilter, the first Esc only leaves the search box). The exit status is the reliable signal: some commands can still print a preselected value on abort, so test$?(or chain|| exit 1) before using the captured variable.gum tableis the exception: Esc or q exits 0 with an empty line, so check the captured row as well. - Many flags expose environment defaults such as
GUM_CHOOSE_CURSORandGUM_INPUT_PLACEHOLDER; check the subcommand help for the exact names. Selection flags such aschoose --limitand--no-limithave no env binding.gum styleuses bare names (FOREGROUND,BORDER,PADDING). - Style flags share a shape:
--<part>.foreground,--<part>.background, and often--padding "0 1". Colors are ANSI indexes or hex. style,join,format, andtable --printwrite through a color profile writer: when stdout is not a terminal (a pipe, a file, or$(...)) the ANSI styling is stripped and the borders and layout stay.CLICOLOR_FORCE=1keeps the colors andNO_COLOR=1removes them.--timeout 30sends an interactive command after the duration.confirmthen returns its default; the other prompts print "timed out" and exit 124.- Options arrive as arguments or one per line on stdin. Output is one
selection per line; change with
--output-delimiter.
Prompts
# pick one, or several (x or tab toggles, a selects all)
format=$(gum choose --header "Format" JSON YAML TOML) || exit 1
tasks=$(printf '%s\n' "List files" "Show size" | \
gum choose --no-limit --selected='*' --ordered --header "Tasks") || exit 1
[[ -n $tasks ]] || exit 0 # --no-limit allows confirming an empty selection
# fuzzy search over a long list
file=$(find . -type f -name '*.md' | gum filter --placeholder "Which Markdown file?") || exit 1
# text
name=$(gum input --placeholder "project name" --header "Name") || exit 1
msg=$(gum write --header "Commit message" --placeholder "what changed?" --char-limit 500) || exit 1
# a directory (needs at least one subdirectory to choose from)
dir=$(gum file . --directory --file=false --all) || exit 1
# yes or no
if gum confirm "List files in the current directory?"; then
ls -la .
fi
confirm exits 0 for the affirmative and 1 for the negative or Esc. Ctrl+c
returns a nonzero status. An if branch runs only on success. In write,
Enter submits and Ctrl+J inserts a newline.
spin
gum spin --spinner dot --show-output --title "Listing files" -- find . -type f
gum spin --show-output --title "Measuring directory" -- du -sh .
The command's exit status is gum's exit status. --show-output streams both
stdout and stderr. With --show-output alone, a failing command's output is
discarded; add --show-error to print it. These flags apply only when stdout
is a terminal. When stdout is a pipe, a file, or $(...), gum hands it to the
command directly, so its stdout is captured with or without --show-output,
even when it fails. --timeout makes gum stop waiting and exit 124, but the
command keeps running; wrap it in timeout(1) when it must stop.
Output commands
gum style --foreground 212 --border double --padding "1 3" "Project tasks"
gum join --horizontal --align top "$left" "$right"
gum format < README.md
gum table --print --border rounded --file status.csv
gum pager < CHANGELOG.md
gum log --structured --level info "task completed" task "List files"
Read references/commands.md for the style flags and
env defaults, join layouts, format types (code, template, emoji) and
themes, interactive table row selection, pager sear