425 lines
150 KiB
Markdown
425 lines
150 KiB
Markdown
|
---
|
||
|
|
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]
|
||
|
|
|
||
|
|
## 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 [<options> ...]`
|
||
|
|
|
||
|
|
| 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 [<prompt>]`
|
||
|
|
|
||
|
|
| 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 [<path>]`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| -------------------------------- | ---------------------------------- | ------------------------------------------------ |
|
||
|
|
| `[<path>]` | `$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 [<options> ...]`
|
||
|
|
|
||
|
|
| 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 [<template> ...]`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ----------------------- | ---------------------- | ----------------------------------------------------------------------- |
|
||
|
|
| `[<template> ...]` | - | Template string to format (can also be provided via stdin) |
|
||
|
|
| `--theme="pink"` | `$GUM_FORMAT_THEME` | Glamour theme to use for [markdown](../../files/Markdown.md) formatting |
|
||
|
|
| `-l, --language="" ` | `$GUM_FORMAT_LANGUAGE` | Programming language to parse code |
|
||
|
|
| `-t, --type="markdown"` | `$GUM_FORMAT_TYPE` | Format to use (`markdown`, `template`, `code`, `emoji`) |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
format processes and formats bodies of text. `gum format` can parse [markdown](../../files/Markdown.md), template strings, and named emojis.
|
||
|
|
```shell
|
||
|
|
# Format some markdown
|
||
|
|
gum format -- "# Gum Formats" "- Markdown" "- Code" "- Template" "- Emoji"
|
||
|
|
echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
|
||
|
|
|
||
|
|
# Syntax highlight some code
|
||
|
|
cat main.go | gum format -t code
|
||
|
|
|
||
|
|
# Render text any way you want with templates
|
||
|
|
echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
|
||
|
|
| gum format -t template
|
||
|
|
|
||
|
|
# Display your favorite emojis!
|
||
|
|
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum input
|
||
|
|
Prompt for some input
|
||
|
|
Usage: `gum input`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ----------------------------------- | ------------------------------ | -------------------------------------------- |
|
||
|
|
| `--placeholder="Type something..."` | `$GUM_INPUT_PLACEHOLDER` | Placeholder value |
|
||
|
|
| `--prompt="> "` | `$GUM_INPUT_PROMPT` | Prompt to display |
|
||
|
|
| `--cursor.mode="blink"` | `$GUM_INPUT_CURSOR_MODE` | Cursor mode |
|
||
|
|
| `--value=""` | - | Initial value (can also be passed via stdin) |
|
||
|
|
| `--char-limit=400` | - | Maximum value length (0 for no limit) |
|
||
|
|
| `--width=40` | `$GUM_INPUT_WIDTH` | Input width (0 for terminal width) |
|
||
|
|
| `--password` | - | Mask input characters |
|
||
|
|
| `--header=""` | `$GUM_INPUT_HEADER` | Header value |
|
||
|
|
| `--timeout=0` | `$GUM_INPUT_TIMEOUT` | Timeout until input aborts |
|
||
|
|
| `--prompt.foreground=""` | `$GUM_INPUT_PROMPT_FOREGROUND` | Foreground Color |
|
||
|
|
| `--cursor.foreground="212"` | `$GUM_INPUT_CURSOR_FOREGROUND` | Foreground Color |
|
||
|
|
| `--header.foreground="240"` | `$GUM_INPUT_HEADER_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
Prompt for input with a simple command.
|
||
|
|
```shell
|
||
|
|
gum input > answer.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
Prompt for sensitive input with the --password flag.
|
||
|
|
```shell
|
||
|
|
gum input --password > password.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum join
|
||
|
|
Join text vertically or horizontally
|
||
|
|
Usage: `gum join <text> ...`
|
||
|
|
|
||
|
|
| Option | Description |
|
||
|
|
| ---------------- | -------------------------------------------------- |
|
||
|
|
| `--align="left"` | Text alignment |
|
||
|
|
| `--horizontal` | Join (potentially multi-line) strings horizontally |
|
||
|
|
| `--vertical` | Join (potentially multi-line) strings vertically |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
Combine text vertically or horizontally. Use this command with `gum style` to build layouts and pretty output.
|
||
|
|
|
||
|
|
> Tip: Always wrap the output of `gum style` in quotes to preserve newlines (`\n`) when using it as an argument in the join command.
|
||
|
|
|
||
|
|
```shell
|
||
|
|
I=$(gum style --padding "1 5" --border double --border-foreground 212 "I")
|
||
|
|
LOVE=$(gum style --padding "1 4" --border double --border-foreground 57 "LOVE")
|
||
|
|
BUBBLE=$(gum style --padding "1 8" --border double --border-foreground 255 "Bubble")
|
||
|
|
GUM=$(gum style --padding "1 5" --border double --border-foreground 240 "Gum")
|
||
|
|
|
||
|
|
I_LOVE=$(gum join "$I" "$LOVE")
|
||
|
|
BUBBLE_GUM=$(gum join "$BUBBLE" "$GUM")
|
||
|
|
gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum pager
|
||
|
|
Scroll through a file
|
||
|
|
Usage: `gum pager [<content>]`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ------------------------------------ | ----------------------------------- | --------------------------- |
|
||
|
|
| `--show-line-numbers` | - | Show line numbers |
|
||
|
|
| `--soft-wrap` | - | Soft wrap lines |
|
||
|
|
| `--timeout=0` | `$GUM_PAGER_TIMEOUT` | Timeout until command exits |
|
||
|
|
| `--foreground=""` | `$GUM_PAGER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--help.foreground="241"` | `$GUM_PAGER_HELP_FOREGROUND` | Foreground Color |
|
||
|
|
| `--line-number.foreground="237"` | `$GUM_PAGER_LINE_NUMBER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--match.foreground="212"` | `$GUM_PAGER_MATCH_FOREGROUND` | Foreground Color |
|
||
|
|
| `--match-highlight.foreground="235"` | `$GUM_PAGER_MATCH_HIGH_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
Scroll through a long document with line numbers and a fully customizable viewport.
|
||
|
|
```shell
|
||
|
|
gum pager < README.md
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum spin
|
||
|
|
Display spinner while running a command
|
||
|
|
Usage: `gum spin <command> ...`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ---------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
|
|
| `--show-output` | `$GUM_SPIN_SHOW_OUTPUT` | Show or pipe output of command during execution |
|
||
|
|
| `-s, --spinner="dot"` | `$GUM_SPIN_SPINNER` | Spinner type. Available spinner types include: `line`, `dot`, `minidot`, `jump`, `pulse`, `points`, `globe`, `moon`, `monkey`, `meter`, `hamburger`. |
|
||
|
|
| `--title="Loading..."` | `$GUM_SPIN_TITLE` | Text to display to user while spinning |
|
||
|
|
| `-a, --align="left"` | `$GUM_SPIN_ALIGN` | Alignment of spinner with regard to the title |
|
||
|
|
| `--timeout=0` | `$GUM_SPIN_TIMEOUT` | Timeout until spin command aborts |
|
||
|
|
| `--spinner.foreground="212"` | `$GUM_SPIN_SPINNER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--title.foreground=""` | `$GUM_SPIN_TITLE_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
To view or pipe the command's output, use the `--show-output` flag.
|
||
|
|
```shell
|
||
|
|
gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum style
|
||
|
|
Apply coloring, borders, spacing to text
|
||
|
|
Usage: `gum style [<text> ...]`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ------------------------ | -------------------- | ----------------------- |
|
||
|
|
| `--foreground=""` | `$FOREGROUND` | Foreground Color |
|
||
|
|
| `--background=""` | `$BACKGROUND` | Background Color |
|
||
|
|
| `--border="none"` | `$BORDER` | Border Style |
|
||
|
|
| `--border-background=""` | `$BORDER_BACKGROUND` | Border Background Color |
|
||
|
|
| `--border-foreground=""` | `$BORDER_FOREGROUND` | Border Foreground Color |
|
||
|
|
| `--align="left"` | `$ALIGN` | Text Alignment |
|
||
|
|
| `--height=0` | `$HEIGHT` | Text height |
|
||
|
|
| `--width=0` | `$WIDTH` | Text width |
|
||
|
|
| `--margin="0 0"` | `$MARGIN` | Text margin |
|
||
|
|
| `--padding="0 0"` | `$PADDING` | Text padding |
|
||
|
|
| `--bold` | `$BOLD` | Bold text |
|
||
|
|
| `--faint` | `$FAINT` | Faint text |
|
||
|
|
| `--italic` | `$ITALIC` | Italicize text |
|
||
|
|
| `--strikethrough` | `$STRIKETHROUGH` | Strikethrough text |
|
||
|
|
| `--underline` | `$UNDERLINE` | Underline text |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
Pretty print any string with any layout with one command.
|
||
|
|
```shell
|
||
|
|
gum style \
|
||
|
|
--foreground 212 --border-foreground 212 --border double \
|
||
|
|
--align center --width 50 --margin "1 2" --padding "2 4" \
|
||
|
|
'Bubble Gum (1¢)' 'So sweet and so fresh!'
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum table
|
||
|
|
Render a table of data
|
||
|
|
Usage: `gum table`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ----------------------------- | -------------------------------- | ---------------- |
|
||
|
|
| `-s, --separator=","` | - | Row separator |
|
||
|
|
| `-c, --columns=COLUMNS,...` | - | Column names |
|
||
|
|
| `-w, --widths=WIDTHS,...` | - | Column widths |
|
||
|
|
| `--height=10` | - | Table height |
|
||
|
|
| `-p, --print` | - | static print |
|
||
|
|
| `-f, --file=""` | - | file path |
|
||
|
|
| `-b, --border="rounded"` | - | border style |
|
||
|
|
| `--border.foreground=""` | `$GUM_TABLE_BORDER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--cell.foreground=""` | `$GUM_TABLE_CELL_FOREGROUND` | Foreground Color |
|
||
|
|
| `--header.foreground=""` | `$GUM_TABLE_HEADER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--selected.foreground="212"` | `$GUM_TABLE_SELECTED_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
Select a row from some tabular data.
|
||
|
|
```shell
|
||
|
|
gum table < flavors.csv | cut -d ',' -f 1
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum write
|
||
|
|
Prompt for long-form text
|
||
|
|
Usage: `gum write`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| ------------------------------------- | ------------------------------------------ | --------------------------------------- |
|
||
|
|
| `--width=50` | `$GUM_WRITE_WIDTH` | Text area width (0 for terminal width) |
|
||
|
|
| `--height=5` | `$GUM_WRITE_HEIGHT` | Text area height |
|
||
|
|
| `--header=""` | `$GUM_WRITE_HEADER` | Header value |
|
||
|
|
| `--placeholder="Write something..."` | `$GUM_WRITE_PLACEHOLDER` | Placeholder value |
|
||
|
|
| `--prompt="┃ "` | `$GUM_WRITE_PROMPT` | Prompt to display |
|
||
|
|
| `--show-cursor-line` | `$GUM_WRITE_SHOW_CURSOR_LINE` | Show cursor line |
|
||
|
|
| `--show-line-numbers` | `$GUM_WRITE_SHOW_LINE_NUMBERS` | Show line numbers |
|
||
|
|
| `--value=""` | `$GUM_WRITE_VALUE` | Initial value (can be passed via stdin) |
|
||
|
|
| `--char-limit=400` | - | Maximum value length (0 for no limit) |
|
||
|
|
| `--cursor.mode="blink"` | `$GUM_WRITE_CURSOR_MODE` | Cursor mode |
|
||
|
|
| `--base.foreground=""` | `$GUM_WRITE_BASE_FOREGROUND` | Foreground Color |
|
||
|
|
| `--cursor-line-number.foreground="7"` | `$GUM_WRITE_CURSOR_LINE_NUMBER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--cursor-line.foreground=""` | `$GUM_WRITE_CURSOR_LINE_FOREGROUND` | Foreground Color |
|
||
|
|
| `--cursor.foreground="212"` | `$GUM_WRITE_CURSOR_FOREGROUND` | Foreground Color |
|
||
|
|
| `--end-of-buffer.foreground="0"` | `$GUM_WRITE_END_OF_BUFFER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--line-number.foreground="7"` | `$GUM_WRITE_LINE_NUMBER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--header.foreground="240"` | `$GUM_WRITE_HEADER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--placeholder.foreground="240"` | `$GUM_WRITE_PLACEHOLDER_FOREGROUND` | Foreground Color |
|
||
|
|
| `--prompt.foreground="7"` | `$GUM_WRITE_PROMPT_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
> Note: `CTRL+D` is used to complete text entry. `CTRL+C` and `esc` will cancel.
|
||
|
|
```shell
|
||
|
|
gum write > story.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
### gum log
|
||
|
|
[Log](../../dev/Log.md) messages to output
|
||
|
|
Usage: `gum log <text> ...`
|
||
|
|
|
||
|
|
| Option | Environment Variable | Description |
|
||
|
|
| --------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
|
||
|
|
| `-o, --file=STRING` | - | Log to file |
|
||
|
|
| `-f, --format` | - | Format message using printf |
|
||
|
|
| `--formatter="text"` | - | The log formatter to use |
|
||
|
|
| `-l, --level="none"` | - | The log level to use |
|
||
|
|
| `--prefix=STRING` | - | Prefix to print before the message |
|
||
|
|
| `-s, --structured` | - | Use structured logging |
|
||
|
|
| `-t, --time=""` | - | The time format to use (`kitchen`, `layout`, `ansic`, `rfc822`, etc...) |
|
||
|
|
| `--level.foreground=""` | `$GUM_LOG_LEVEL_FOREGROUND` | Foreground Color |
|
||
|
|
| `--time.foreground=""` | `$GUM_LOG_TIME_FOREGROUND` | Foreground Color |
|
||
|
|
| `--prefix.foreground=""` | `$GUM_LOG_PREFIX_FOREGROUND` | Foreground Color |
|
||
|
|
| `--message.foreground=""` | `$GUM_LOG_MESSAGE_FOREGROUND` | Foreground Color |
|
||
|
|
| `--key.foreground=""` | `$GUM_LOG_KEY_FOREGROUND` | Foreground Color |
|
||
|
|
| `--value.foreground=""` | `$GUM_LOG_VALUE_FOREGROUND` | Foreground Color |
|
||
|
|
| `--separator.foreground=""` | `$GUM_LOG_SEPARATOR_FOREGROUND` | Foreground Color |
|
||
|
|
|
||
|
|
**Example**:
|
||
|
|
`log` logs messages to the terminal at using different levels and styling using the charmbracelet/log library.
|
||
|
|
```shell
|
||
|
|
# Log some debug information.
|
||
|
|
gum log --structured --level debug "Creating file..." name file.txt
|
||
|
|
# DEBUG Unable to create file. name=temp.txt
|
||
|
|
|
||
|
|
# Log some error.
|
||
|
|
gum log --structured --level error "Unable to create file." name file.txt
|
||
|
|
# ERROR Unable to create file. name=temp.txt
|
||
|
|
|
||
|
|
# Include a timestamp.
|
||
|
|
gum log --time rfc822 --level error "Unable to create file."
|
||
|
|
```
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
### Connect to a [TMUX](tmux.md) session
|
||
|
|
Pick from a running [tmux](tmux.md) session and attach to it. Or, if you're already in a [tmux](tmux.md) session, switch sessions.
|
||
|
|
```shell
|
||
|
|
SESSION=$(tmux list-sessions -F \#S | gum filter --placeholder "Pick session...")
|
||
|
|
tmux switch-client -t $SESSION || tmux attach -t $SESSION
|
||
|
|
```
|
||
|
|
|
||
|
|
### Pick commit hash from your [Git](../../dev/Git.md) history
|
||
|
|
Filter through your [git](../../dev/Git.md) history searching for commit messages, copying the commit hash of the commit you select.
|
||
|
|
```shell
|
||
|
|
git log --oneline | gum filter | cut -d' ' -f1 # | copy
|
||
|
|
```
|
||
|
|
|
||
|
|
### Choose packages to uninstall
|
||
|
|
List all packages installed by your package manager (we'll use [brew](../package%20managers/Brew.md)) and choose which packages to uninstall.
|
||
|
|
```shell
|
||
|
|
brew list | gum choose --no-limit | xargs brew uninstall
|
||
|
|
```
|
||
|
|
|
||
|
|
### Choose branches to delete
|
||
|
|
List all branches and choose which branches to delete.
|
||
|
|
```shell
|
||
|
|
git branch | cut -c 3- | gum choose --no-limit | xargs git branch -D
|
||
|
|
```
|
||
|
|
|
||
|
|
[Gum]: data:image/avif;base64,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
|