--- obj: application repo: https://github.com/charmbracelet/gum rev: 2024-03-27 --- # gum Gum provides highly configurable, ready-to-use utilities to help you write useful [shell](Shell.md) scripts and dotfiles aliases with just a few lines of code. ![Gum](./gum.avif) ## Usage **Example:** ```shell #!/bin/sh TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert") SCOPE=$(gum input --placeholder "scope") # Since the scope is optional, wrap it in parentheses if it has a value. test -n "$SCOPE" && SCOPE="($SCOPE)" # Pre-populate the input with the type(scope): so that the user may change it SUMMARY=$(gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change") DESCRIPTION=$(gum write --placeholder "Details of this change (CTRL+D to finish)") # Commit these changes gum confirm "Commit changes?" && git commit -m "$SUMMARY" -m "$DESCRIPTION" ``` ### gum choose Choose an option from a list of choices Usage: `gum choose [ ...]` | Option | Environment Variable | Description | | ----------------------------- | --------------------------------- | -------------------------------------------------------------- | | `--ordered` | `$GUM_CHOOSE_ORDERED` | Maintain the order of the selected options | | `--height=10` | `$GUM_CHOOSE_HEIGHT` | Height of the list | | `--cursor="> "` | `$GUM_CHOOSE_CURSOR` | Prefix to show on item that corresponds to the cursor position | | `--header=""` | `$GUM_CHOOSE_HEADER` | Header value | | `--cursor-prefix="○ "` | `$GUM_CHOOSE_CURSOR_PREFIX` | Prefix to show on the cursor item (hidden if limit is 1) | | `--selected-prefix="◉ "` | `$GUM_CHOOSE_SELECTED_PREFIX` | Prefix to show on selected items (hidden if limit is 1) | | `--unselected-prefix="○ "` | `$GUM_CHOOSE_UNSELECTED_PREFIX` | Prefix to show on unselected items (hidden if limit is 1) | | `--selected=,...` | `$GUM_CHOOSE_SELECTED` | Options that should start as selected | | `--timeout=0` | `$GUM_CCHOOSE_TIMEOUT` | Timeout until choose returns selected element | | `--limit=1` | - | Maximum number of options to pick | | `--no-limit` | - | Pick unlimited number of options (ignores limit) | | `--select-if-one` | - | Select the given option if there is only one | | `--cursor.foreground="212"` | `$GUM_CHOOSE_CURSOR_FOREGROUND` | Foreground Color | | `--header.foreground="240"` | `$GUM_CHOOSE_HEADER_FOREGROUND` | Foreground Color | | `--item.foreground=""` | `$GUM_CHOOSE_ITEM_FOREGROUND` | Foreground Color | | `--selected.foreground="212"` | `$GUM_CHOOSE_SELECTED_FOREGROUND` | Foreground Color | **Example**: Choose an option from a list of choices. ```shell echo "Pick a card, any card..." CARD=$(gum choose --height 15 {{A,K,Q,J},{10..2}}" "{♠,♥,♣,♦}) echo "Was your card the $CARD?" ``` ### gum confirm Ask a user to confirm an action Usage: `gum confirm []` | Option | Environment Variable | Description | | ------------------------------- | ------------------------------------ | ------------------------------------------------------------------- | | `--default` | - | Default confirmation action | | `--affirmative="Yes"` | - | The title of the affirmative action | | `--negative="No"` | - | The title of the negative action | | `--timeout=0` | `$GUM_CONFIRM_TIMEOUT` | Timeout until confirm returns selected value or default if provided | | `--prompt.foreground=""` | `$GUM_CONFIRM_PROMPT_FOREGROUND` | Foreground Color | | `--selected.foreground="230"` | `$GUM_CONFIRM_SELECTED_FOREGROUND` | Foreground Color | | `--unselected.foreground="254"` | `$GUM_CONFIRM_UNSELECTED_FOREGROUND` | Foreground Color | **Example**: Confirm whether to perform an action. Exits with code 0 (affirmative) or 1 (negative) depending on selection. ```shell gum confirm && rm file.txt || echo "File not removed" ``` ### gum file Pick a file from a folder Usage: `gum file []` | Option | Environment Variable | Description | | -------------------------------- | ---------------------------------- | ------------------------------------------------ | | `[]` | `$GUM_FILE_PATH` | The path to the folder to begin traversing | | `-c, --cursor=">"` | `$GUM_FILE_CURSOR` | The cursor character | | `-a, --all` | `$GUM_FILE_ALL` | Show hidden and 'dot' files | | `--file` | `$GUM_FILE_FILE` | Allow files selection | | `--directory` | `$GUM_FILE_DIRECTORY` | Allow directories selection | | `--height=0` | `$GUM_FILE_HEIGHT` | Maximum number of files to display | | `--timeout=0` | `$GUM_FILE_TIMEOUT` | Timeout until command aborts without a selection | | `--cursor.foreground="212"` | `$GUM_FILE_CURSOR_FOREGROUND` | Foreground Color | | `--symlink.foreground="36"` | `$GUM_FILE_SYMLINK_FOREGROUND` | Foreground Color | | `--directory.foreground="99"` | `$GUM_FILE_DIRECTORY_FOREGROUND` | Foreground Color | | `--file.foreground="" ` | `$GUM_FILE_FILE_FOREGROUND` | Foreground Color | | `--permissions.foreground="244"` | `$GUM_FILE_PERMISSIONS_FOREGROUND` | Foreground Color | | `--selected.foreground="212"` | `$GUM_FILE_SELECTED_FOREGROUND` | Foreground Color | | `--file-size.foreground="240"` | `$GUM_FILE_FILE_SIZE_FOREGROUND` | Foreground Color | **Example**: Prompt the user to select a file from the file tree. ```shell EDITOR $(gum file $HOME) ``` ### gum filter Filter items from a list Usage: `gum filter [ ...]` | Option | Environment Variable | Description | | --------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- | | `--indicator="•`" | `$GUM_FILTER_INDICATOR` | Character for selection | | `--selected-prefix=" ◉ "` | `$GUM_FILTER_SELECTED_PREFIX` | Character to indicate selected items (hidden if limit is 1) | | `--unselected-prefix=" ○ "` | `$GUM_FILTER_UNSELECTED_PREFIX` | Character to indicate unselected items (hidden if limit is 1) | | `--header=""` | `$GUM_FILTER_HEADER` | Header value | | `--placeholder="Filter..."` | `$GUM_FILTER_PLACEHOLDER` | Placeholder value | | `--prompt="> "` | `$GUM_FILTER_PROMPT` | Prompt to display | | `--width=20` | `$GUM_FILTER_WIDTH` | Input width | | `--height=0` | `$GUM_FILTER_HEIGHT` | Input height | | `--value=""` | `$GUM_FILTER_VALUE` | Initial filter value | | `--reverse` | `$GUM_FILTER_REVERSE` | Display from the bottom of the screen | | `--[no-]fuzzy` | `$GUM_FILTER_FUZZY` | Enable fuzzy matching | | `--[no-]sort` | `$GUM_FILTER_SORT` | Sort the results | | `--timeout=0` | `$GUM_FILTER_TIMEOUT` | Timeout until filter command aborts | | `--indicator.foreground="212"` | `$GUM_FILTER_INDICATOR_FOREGROUND` | Foreground Color | | `--selected-indicator.foreground="212"` | `$GUM_FILTER_SELECTED_PREFIX_FOREGROUND` | Foreground Color | | `--unselected-prefix.foreground="240"` | `$GUM_FILTER_UNSELECTED_PREFIX_FOREGROUND` | Foreground Color | | `--header.foreground="240"` | `$GUM_FILTER_HEADER_FOREGROUND` | Foreground Color | | `--text.foreground=""` | `$GUM_FILTER_TEXT_FOREGROUND` | Foreground Color | | `--cursor-text.foreground=""` | `$GUM_FILTER_CURSOR_TEXT_FOREGROUND` | Foreground Color | | `--match.foreground="212"` | `$GUM_FILTER_MATCH_FOREGROUND` | Foreground Color | | `--prompt.foreground="240"` | `$GUM_FILTER_PROMPT_FOREGROUND` | Foreground Color | | `--limit=1` | - | Maximum number of options to pick | | `--no-limit` | - | Pick unlimited number of options (ignores limit) | | `--select-if-one` | - | Select the given option if there is only one | | `--[no-]strict` | - | Only returns if anything matched. Otherwise return Filter | **Example**: Use fuzzy matching to filter a list of values: ```shell echo Strawberry >> flavors.txt echo Banana >> flavors.txt echo Cherry >> flavors.txt cat flavors.txt | gum filter > selection.txt ``` ### gum format Format a string using a template Usage: `gum format [