How to Use the Command 'gum' (with Examples)

The gum command is an innovative tool used to create visually appealing and interactive shell scripts. It allows users to incorporate a variety of interactive elements into their scripts, enhancing the user experience by offering functionalities such as interactive prompts, spinners, and text formatting with emojis. This command is particularly helpful for developers who wish to create scripts that are not only functional but also provide an engaging user experience. Below are a few use cases illustrating different functionalities of the gum command.

Use Case 1: Interactively Pick a Specific Option to Print to stdout

Code:

gum choose "option_1" "option_2" "option_3"

Motivation: When designing a script that requires user input, allowing users to choose from predefined options can streamline the process. By using gum choose, the script becomes user-friendly and minimizes the potential for input errors compared to manually typing input.

Explanation:

• gum choose: This is the primary command for generating a selection menu.
• "option_1" "option_2" "option_3": These arguments represent the choices a user can select from. They are enclosed in quotes to ensure they are treated as distinct options.

Example Output:

option_2

(In this example, the user selected “option_2” from the interactive options.)

Use Case 2: Open an Interactive Prompt for User Input

Code:

gum input --placeholder "value"

Motivation: Interactive input prompts are essential for scripts requiring user-defined strings. With a placeholder, users have guidance regarding the expected input format, enhancing usability and reducing errors.

Explanation:

• gum input: This initiates a prompt for the user to provide input.
• --placeholder "value": This option helps the user understand what type of input is expected, acting as a hint until actual input is provided.

Example Output:

Please enter a value: John

(The placeholder “value” appears in the input field until the user types “John.”)

Use Case 3: Open an Interactive Confirmation Prompt

Code:

gum confirm "Continue?" --default=false --affirmative "Yes" --negative "No" && echo "Yes selected" || echo "No selected"

Motivation: Confirmation prompts are advantageous in scripts requiring a user’s decision to proceed, ensuring critical operations are not executed accidentally. This example provides a binary choice with custom affirmation and negation options.

Explanation:

• gum confirm "Continue?": Displays a confirmation prompt to the user.
• --default=false: Sets the default state to “No” unless the user specifically selects “Yes.”
• --affirmative "Yes" and --negative "No": Customize the textual representation of the options presented to the user.
• && echo "Yes selected" || echo "No selected": Depending on the user’s choice, the corresponding message is echoed as a result.

Example Output:

Continue? (default: No) [Yes/No]
No selected

(The user did not change the default, thus selecting “No.”)

Use Case 4: Show a Spinner While a Command is Taking Place

Code:

gum spin --spinner dot --title "loading..." -- sleep 5

Motivation: Long-running commands can leave users unsure of a script’s progress. By implementing a spinner, users are visually informed that the process is ongoing, improving script transparency and user satisfaction.

Explanation:

• gum spin: Initiates a wait indicator, signifying in-progress operations.
• --spinner dot: Chooses the animation style of the spinner.
• --title "loading...": Text displayed alongside the spinner to inform users about the activity.
• -- sleep 5: Simulates a command that takes time to execute, such as a 5-second wait in this case.

Example Output:

[•••••••] loading...

(A spinner alongside the title “loading…” indicates an ongoing process.)

Use Case 5: Format Text to Include Emojis

Code:

gum format -t emoji ":smile: :heart: hello"

Motivation: Adding emojis to scripts can enrich the user experience by making text more visually dynamic and conveying emotions effectively. This is especially useful in scripts intended for interactive usage or documentation.

Explanation:

• gum format: Utilizes formatting capabilities for text manipulation.
• -t emoji: Specifies that the text is to be formatted to include emoji representations.
• ":smile: :heart: hello": A string containing emoji shorthand and regular text that will be converted into a visually-enhanced output.

Example Output:

😄 ❤️ hello

(The text is displayed with emojis corresponding to the shorthand provided.)

Use Case 6: Interactively Prompt for Multi-Line Text

Code:

gum write > data.txt

Motivation: Sometimes scripts need to capture detailed input, such as notes or messages, that span multiple lines. By enabling users to provide multiline input interactively, scripts become more versatile and user-friendly.

Explanation:

• gum write: Opens an interactive environment where users can type multiple lines of text.
• > data.txt: Redirects the user’s input into a file named data.txt for later use or processing.

Example Output:

The input would look like:

This is a multiline
text input
saved to a file.

(The above lines are saved to data.txt upon completion.)

Conclusion

The gum command greatly enhances the functionality of shell scripts by introducing interactive and engaging elements. With its diverse use cases—from interactive option picking to emoji formatting—it transforms conventional scripts into more user-friendly applications. By leveraging gum, developers can create scripts that not only perform tasks efficiently but also provide an enriched user experience.