GUM(1)

📦

version 2.0.2 · 10 versions

2.0.2 · arch rolling (latest)
0.17.0 · nixos 26.05
2.0.2 · nixpkgs unstable
0.16.2 · alpine 3.24
0.14.4 · ubuntu questing
0.16.2 · fedora 43
0.17.0 · epel 10, fedora 44
0.17.0 · fedora 44
0.17.0 · ubuntu resolute, ubuntu stonking
0.14.4 · debian trixie

💅 GUM 💅

okay so you've pulled up the manual page for gum — yes, that gum, the one from section 1 of the manual, bestie. Subtitle on the tin: A tool for glamorous shell scripts. Which, like, is the whole personality. Let's get into it 🫶

✨ NAME ✨

gum — A tool for glamorous shell scripts. that's it, that's the name, and honestly it ate 💅

🌸 SYNOPSIS 🌸

gum [options...] [argument...]

🦋 DESCRIPTION 🦋

so, funny thing: this section is literally empty in the original page 😭 no cap, nothing in there. the vibes are doing all the work. moving on 💀

🎀 OPTIONS 🎀

-h, --help — shows you the help, but like, context-sensitive help, so it actually knows where you are 👑
-v, --version — prints the version number, so you can flex how up-to-date you are ✨

🌈 COMMANDS 🌈

🌟 `choose [<options> ...] [flags]`

pick one (or more, we don't judge) from a list of choices. this is the main character of the commands, fr fr 👑

💖 OPTIONS 💖

--cursor-prefix="• " — the prefix that shows up on the cursor item (it goes hidden if limit is 1)
--cursor.align="left" — text alignment
--cursor.background="" — background color
--cursor.bold — bold text
--cursor.border-background="" — border background color
--cursor.border-foreground="" — border foreground color
--cursor.border="none" — border style
--cursor.faint — faint text
--cursor.foreground="212" — foreground color
--cursor.height=0 — text height
--cursor.italic — italicize text
--cursor.margin="0 0" — text margin
--cursor.padding="0 0" — text padding
--cursor.strikethrough — strikethrough text
--cursor.underline — underline text
--cursor.width=0 — text width
--cursor="> " — the prefix on the item that matches where the cursor is sitting rn
--header.align="left" — text alignment
--header.background="" — background color
--header.bold — bold text
--header.border-background="" — border background color
--header.border-foreground="" — border foreground color
--header.border="none" — border style
--header.faint — faint text
--header.foreground="99" — foreground color
--header.height=0 — text height
--header.italic — italicize text
--header.margin="0 0" — text margin
--header.padding="0 0" — text padding
--header.strikethrough — strikethrough text
--header.underline — underline text
--header.width=0 — text width
--header="Choose:" — what the header actually says
--height=10 — how tall the list is
--input-delimiter="\n" — the delimiter used for options when it's reading from STDIN
--item.align="left" — text alignment
--item.background="" — background color
--item.bold — bold text
--item.border-background="" — border background color
--item.border-foreground="" — border foreground color
--item.border="none" — border style
--item.faint — faint text
--item.foreground="" — foreground color
--item.height=0 — text height
--item.italic — italicize text
--item.margin="0 0" — text margin
--item.padding="0 0" — text padding
--item.strikethrough — strikethrough text
--item.underline — underline text
--item.width=0 — text width
--label-delimiter="" — lets you set a delimiter so options can be written as label:value, iconic
--limit=1 — max number of options you're allowed to pick
--no-limit — pick an unlimited number of options (this straight up ignores limit)
--ordered — keeps the selected options in the order they were selected, not the order they appeared
--output-delimiter="\n" — the delimiter used for options when it writes out to STDOUT
--padding="0 0" — padding
--select-if-one — auto-selects the option if there's literally only one of them
--selected-prefix="✓ " — the prefix on selected items (hidden if limit is 1)
--selected.align="left" — text alignment
--selected.background="" — background color
--selected.bold — bold text
--selected.border-background="" — border background color
--selected.border-foreground="" — border foreground color
--selected.border="none" — border style
--selected.faint — faint text
--selected.foreground="212" — foreground color
--selected.height=0 — text height
--selected.italic — italicize text
--selected.margin="0 0" — text margin
--selected.padding="0 0" — text padding
--selected.strikethrough — strikethrough text
--selected.underline — underline text
--selected.width=0 — text width
--selected=,... — options that should start out already selected (pass * and it selects all of them, periodt)
--show-help — shows the help keybinds
--strip-ansi — strips ANSI sequences when reading from STDIN
--timeout=0s — timeout until choose returns the selected element
--unselected-prefix="• " — the prefix on the unselected items (hidden if limit is 1)

🌟 `confirm [<prompt>] [flags]`

asks the user to confirm an action. yes/no moment, very dramatic 🎀

💖 OPTIONS 💖

--affirmative="Yes" — the title of the affirmative action
--default — the default confirmation action
--negative="No" — the title of the negative action
--padding="0 0" — padding
--prompt.align="left" — text alignment
--prompt.background="" — background color
--prompt.bold — bold text
--prompt.border-background="" — border background color
--prompt.border-foreground="" — border foreground color
--prompt.border="none" — border style
--prompt.faint — faint text
--prompt.foreground="#7571F9" — foreground color
--prompt.height=0 — text height
--prompt.italic — italicize text
--prompt.margin="0 0 0 1" — text margin
--prompt.padding="0 0" — text padding
--prompt.strikethrough — strikethrough text
--prompt.underline — underline text
--prompt.width=0 — text width
--selected.align="left" — text alignment
--selected.background="212" — background color
--selected.bold — bold text
--selected.border-background="" — border background color
--selected.border-foreground="" — border foreground color
--selected.border="none" — border style
--selected.faint — faint text
--selected.foreground="230" — foreground color
--selected.height=0 — text height
--selected.italic — italicize text
--selected.margin="0 1" — text margin
--selected.padding="0 3" — text padding
--selected.strikethrough — strikethrough text
--selected.underline — underline text
--selected.width=0 — text width
--show-help — shows the help key binds
--show-output — prints the prompt and the chosen action to the output
--timeout=0s — timeout until confirm returns the selected value, or the default if one was provided
--unselected.align="left" — text alignment
--unselected.background="235" — background color
--unselected.bold — bold text
--unselected.border-background="" — border background color
--unselected.border-foreground="" — border foreground color
--unselected.border="none" — border style
--unselected.faint — faint text
--unselected.foreground="254" — foreground color
--unselected.height=0 — text height
--unselected.italic — italicize text
--unselected.margin="0 1" — text margin
--unselected.padding="0 3" — text padding
--unselected.strikethrough — strikethrough text
--unselected.underline — underline text
--unselected.width=0 — text width

🌟 `file [<path>] [flags]`

pick a file out of a folder. little file browser moment 📁✨

💖 OPTIONS 💖

-a, --all — show hidden and 'dot' files too, no secrets 👀
--cursor.align="left" — text alignment
--cursor.background="" — background color
--cursor.bold — bold text
--cursor.border-background="" — border background color
--cursor.border-foreground="" — border foreground color
--cursor.border="none" — border style
--cursor.faint — faint text
--cursor.foreground="212" — foreground color
--cursor.height=0 — text height
--cursor.italic — italicize text
--cursor.margin="0 0" — text margin
--cursor.padding="0 0" — text padding
--cursor.strikethrough — strikethrough text
--cursor.underline — underline text
--cursor.width=0 — text width
-c, --cursor=">" — the cursor character itself
--directory — allow directory selection, so folders are fair game
--directory.align="left" — text alignment
--directory.background="" — background color
--directory.bold — bold text
--directory.border-background="" — border background color
--directory.border-foreground="" — border foreground color
--directory.border="none" — border style
--directory.faint — faint text
--directory.foreground="99" — foreground color
--directory.height=0 — text height
--directory.italic — italicize text
--directory.margin="0 0" — text margin
--directory.padding="0 0" — text padding
--directory.strikethrough — puts a lil strike through the directory text 🎀
--directory.underline — underlines the directory text, very demure
--directory.width=0 — text width for the directory column
--file — yes bestie, this lets you select actual files 💖
--file-size.align="right" — text alignment for the file size
--file-size.background="" — background colour
--file-size.bold — bold text, main character behaviour
--file-size.border-background="" — border background colour
--file-size.border-foreground="" — border foreground colour
--file-size.border="none" — border style
--file-size.faint — faint text (shy text)
--file-size.foreground="240" — foreground colour
--file-size.height=0 — text height
--file-size.italic — italicize text, fancy fr
--file-size.margin="0 0" — text margin
--file-size.padding="0 0" — text padding
--file-size.strikethrough — strikethrough text
--file-size.underline — underline text
--file-size.width=8 — text width
--file.align="left" — text alignment
--file.background="" — background colour
--file.bold — bold text
--file.border-background="" — border background colour
--file.border-foreground="" — border foreground colour
--file.border="none" — border style
--file.faint — faint text
--file.foreground="" — foreground colour
--file.height=0 — text height
--file.italic — italicize text
--file.margin="0 0" — text margin
--file.padding="0 0" — text padding
--file.strikethrough — strikethrough text
--file.underline — underline text
--file.width=0 — text width
--header.align="left" — text alignment for the header
--header.background="" — background colour
--header.bold — bold text
--header.border-background="" — border background colour
--header.border-foreground="" — border foreground colour
--header.border="none" — border style
--header.faint — faint text
--header.foreground="99" — foreground colour
--header.height=0 — text height
--header.italic — italicize text
--header.margin="0 0" — text margin
--header.padding="0 0" — text padding
--header.strikethrough — strikethrough text
--header.underline — underline text
--header.width=0 — text width
--header="" — the actual header value, like the words at the top ✨
--height=10 — max number of files to display at once
--padding="0 0" — padding
-p, --permissions — show file permissions 👑
--permissions.align="left" — text alignment
--permissions.background="" — background colour
--permissions.bold — bold text
--permissions.border-background="" — border background colour
--permissions.border-foreground="" — border foreground colour
--permissions.border="none" — border style
--permissions.faint — faint text
--permissions.foreground="244" — foreground colour
--permissions.height=0 — text height
--permissions.italic — italicize text
--permissions.margin="0 0" — text margin
--permissions.padding="0 0" — text padding
--permissions.strikethrough — strikethrough text
--permissions.underline — underline text
--permissions.width=0 — text width
--selected.align="left" — text alignment for whatever you've picked
--selected.background="" — background colour
--selected.bold — bold text
--selected.border-background="" — border background colour
--selected.border-foreground="" — border foreground colour
--selected.border="none" — border style
--selected.faint — faint text
--selected.foreground="212" — foreground colour
--selected.height=0 — text height
--selected.italic — italicize text
--selected.margin="0 0" — text margin
--selected.padding="0 0" — text padding
--selected.strikethrough — strikethrough text
--selected.underline — underline text
--selected.width=0 — text width
--show-help — show the help key binds 🫶
-s, --size — show file size
--symlink.align="left" — text alignment
--symlink.background="" — background colour
--symlink.bold — bold text
--symlink.border-background="" — border background colour
--symlink.border-foreground="" — border foreground colour
--symlink.border="none" — border style
--symlink.faint — faint text
--symlink.foreground="36" — foreground colour
--symlink.height=0 — text height
--symlink.italic — italicize text
--symlink.margin="0 0" — text margin
--symlink.padding="0 0" — text padding
--symlink.strikethrough — strikethrough text
--symlink.underline — underline text
--symlink.width=0 — text width
--timeout=0s — timeout until the command just gives up and aborts without a selection 💀 (yes, it will simply leave you on read)

🦋 `filter` [<options> ...] [flags]

Filter items from a list — like a little sieve for your options, and honestly? iconic.

✨ OPTIONS ✨

--cursor-text.align="left" — text alignment for the cursor text
--cursor-text.background="" — background colour
--cursor-text.bold — bold text
--cursor-text.border-background="" — border background colour
--cursor-text.border-foreground="" — border foreground colour
--cursor-text.border="none" — border style
--cursor-text.faint — faint text
--cursor-text.foreground="" — foreground colour
--cursor-text.height=0 — text height
--cursor-text.italic — italicize text
--cursor-text.margin="0 0" — text margin
--cursor-text.padding="0 0" — text padding
--cursor-text.strikethrough — strikethrough text
--cursor-text.underline — underline text
--cursor-text.width=0 — text width
--fuzzy — enable fuzzy matching; otherwise it matches from the start of the word 🔍
--fuzzy-sort — sort fuzzy results by their scores
--header.align="left" — text alignment
--header.background="" — background colour
--header.bold — bold text
--header.border-background="" — border background colour
--header.border-foreground="" — border foreground colour
--header.border="none" — border style
--header.faint — faint text
--header.foreground="99" — foreground colour
--header.height=0 — text height
--header.italic — italicize text
--header.margin="0 0" — text margin
--header.padding="0 0" — text padding
--header.strikethrough — strikethrough text
--header.underline — underline text
--header.width=0 — text width
--header="" — header value
--height=0 — input height
--indicator.align="left" — text alignment
--indicator.background="" — background colour
--indicator.bold — bold text
--indicator.border-background="" — border background colour
--indicator.border-foreground="" — border foreground colour
--indicator.border="none" — border style
--indicator.faint — faint text
--indicator.foreground="212" — foreground colour
--indicator.height=0 — text height
--indicator.italic — italicize text
--indicator.margin="0 0" — text margin
--indicator.padding="0 0" — text padding
--indicator.strikethrough — strikethrough text
--indicator.underline — underline text
--indicator.width=0 — text width
--indicator="•" — the character that marks your selection 🎀
--input-delimiter="\n" — option delimiter when reading from STDIN
--limit=1 — maximum number of options to pick
--match.align="left" — text alignment for the matched bits
--match.background="" — background colour
--match.bold — bold text
--match.border-background="" — border background colour
--match.border-foreground="" — border foreground colour
--match.border="none" — border style
--match.faint — faint text
--match.foreground="212" — foreground colour
--match.height=0 — text height
--match.italic — italicize text
--match.margin="0 0" — text margin
--match.padding="0 0" — text padding
--match.strikethrough — strikethrough text
--match.underline — underline text
--match.width=0 — text width
--no-limit — pick an unlimited number of options (this ignores limit, periodt)
--output-delimiter="\n" — option delimiter when writing to STDOUT
--padding="0 0" — padding
--placeholder.align="left" — text alignment for the placeholder text
--placeholder.background="" — background colour
--placeholder.bold — bold text

…and the style parade keeps marching 💅 every widget in gum has its own little wardrobe, and the pattern is always the same: <widget>.<property>. Slap a value on it and the widget serves a look. Periodt.

--placeholder.border-background="" — the background colour behind the placeholder's border 😌 empty by default.
--placeholder.border-foreground="" — the colour the placeholder's border itself is drawn in. Also empty unless you say otherwise.
--placeholder.border="none" — what style of border the placeholder gets. Default is none, so no box unless you ask 🎀
--placeholder.faint — makes the placeholder text faint. Subtle queen behaviour.
--placeholder.foreground="240" — the placeholder text colour, sitting pretty at 240 by default.
--placeholder.height=0 — how tall the placeholder is, in text terms. 0 means default, no cap.
--placeholder.italic — italicises the placeholder. Slanty vibes ✨
--placeholder.margin="0 0" — margin around the placeholder, 0 0 to start.
--placeholder.padding="0 0" — padding inside the placeholder, also 0 0 out the gate.
--placeholder.strikethrough — draws a line through the placeholder text 💀 dramatic but valid.
--placeholder.underline — underlines the placeholder. Lowkey classic.
--placeholder.width=0 — width of the placeholder. 0 = default behaviour.
--placeholder="Filter..." — the actual placeholder text shown when the field is empty. Defaults to Filter... 🔍

Okay and now the prompt, same energy, different widget 💖

--prompt.align="left" — where the prompt text lines up. Default left, like a sane person.
--prompt.background="" — prompt background colour, empty default.
--prompt.bold — bolds the prompt. Make it loud 📣
--prompt.border-background="" — background behind the prompt's border. Empty unless set.
--prompt.border-foreground="" — colour of the prompt's border line.
--prompt.border="none" — border style for the prompt. none by default 🚫
--prompt.faint — faint prompt text, whispery.
--prompt.foreground="240" — prompt text colour, 240 initially.
--prompt.height=0 — height of the prompt block. 0 = default.
--prompt.italic — italicises the prompt 🦋
--prompt.margin="0 0" — margin around the prompt, 0 0.
--prompt.padding="0 0" — padding inside the prompt, 0 0.
--prompt.strikethrough — strikes through the prompt. Chaotic but it's an option.
--prompt.underline — underlines the prompt, understated slay.
--prompt.width=0 — prompt width, 0 for default.
--prompt="> " — the literal prompt string shown to the user. Default is > , and yes the space matters 💅

Then the filter's actual behaviour knobs, which are the主食 of this whole thing:

--reverse — flips it so stuff displays from the bottom of the screen instead of the top. Main character chaos 🙃
--select-if-one — if there's literally only one option, it just selects it. No need to make the user work for it 🫶
--selected-indicator.align="left" — alignment of the selected indicator. left.
--selected-indicator.background="" — its background colour, empty default.
--selected-indicator.bold — bolds the selected indicator.
--selected-indicator.border-background="" — background behind its border.
--selected-indicator.border-foreground="" — colour of its border.
--selected-indicator.border="none" — border style, none unless changed.
--selected-indicator.faint — faint rendering for the selected indicator.
--selected-indicator.foreground="212" — colour of the selected indicator, defaulting to a very cute 212 🌸
--selected-indicator.height=0 — its height. 0 = default.
--selected-indicator.italic — italicises it.
--selected-indicator.margin="0 0" — margin, 0 0.
--selected-indicator.padding="0 0" — padding, 0 0.
--selected-indicator.strikethrough — strike it through if that's the vibe.
--selected-indicator.underline — underline it instead.
--selected-indicator.width=0 — width, 0 for default.
--selected-prefix=" ◉ " — the lil character marking selected items. Default ◉ — and heads up, it's hidden if limit is 1 🙈
--selected=,... — options that should start out already selected. Give it * and it selects all of them, no cap ⭐
--show-help — shows the help keybinds so nobody's left guessing.
--sort — sorts fuzzy results by their scores. Tidy ✨
--strict — only returns if anything actually matched; otherwise it returns Filter. Choose your fighter.
--strip-ansi — strips ANSI sequences when reading from STDIN. Clean text only 🧼
--text.align="left" — text alignment, left by default.
--text.background="" — text background colour, empty.
--text.bold — bold text.
--text.border-background="" — border background colour.
--text.border-foreground="" — border foreground colour.
--text.border="none" — border style, none.
--text.faint — faint text.
--text.foreground="" — foreground colour. Note this one's empty by default, not 240 👀
--text.height=0 — text height, 0.
--text.italic — italic text.
--text.margin="0 0" — margin, 0 0.
--text.padding="0 0" — padding, 0 0.
--text.strikethrough — strikethrough text.
--text.underline — underlined text.
--text.width=0 — text width, 0.
--timeout=0s — how long before the filter command gives up and aborts. Default 0s ⏰
--unselected-prefix.align="left" — alignment for the unselected prefix, left.
--unselected-prefix.background="" — its background colour, empty.
--unselected-prefix.bold — bolds it.
--unselected-prefix.border-background="" — border background colour.
--unselected-prefix.border-foreground="" — border foreground colour.
--unselected-prefix.border="none" — border style, none.
--unselected-prefix.faint — faint rendering.
--unselected-prefix.foreground="240" — foreground colour, 240.
--unselected-prefix.height=0 — height, 0.
--unselected-prefix.italic — italicise it.
--unselected-prefix.margin="0 0" — margin, 0 0.
--unselected-prefix.padding="0 0" — padding, 0 0.
--unselected-prefix.strikethrough — strikethrough.
--unselected-prefix.underline — underline.
--unselected-prefix.width=0 — width, 0.
--unselected-prefix=" ○ " — the character that marks unselected items. Default ○, and it's hidden if limit is 1 🫥
--value="" — the initial filter value, empty by default.
--width=0 — input width. 0 means default.

🎀 `format` `[<template> ...]` `[flags]`

This one formats a string using a template. Glow-up for your text, basically 💖

OPTIONS

-l, --language="" — the programming language to parse code with. Empty by default.
--strip-ansi — strips ANSI sequences when reading from STDIN. Again, squeaky clean 🧼
--theme="pink" — the Glamour theme used for markdown formatting. Defaults to pink — taste, honestly 💅
-t, --type="markdown" — which format to use. Options are markdown, template, code, emoji. Default is markdown ✨

🌸 `input` `[flags]`

Prompts you for some input. It's giving interactive, it's giving conversation 🫶

OPTIONS

--char-limit=400 — max length of the value. Set it to 0 for no limit at all. Default is 400.
--cursor.align="left" — cursor text alignment, left.
--cursor.background="" — cursor background colour, empty.
--cursor.bold — bold cursor.
--cursor.border-background="" — border background colour.
--cursor.border-foreground="" — border foreground colour.
--cursor.border="none" — border style, none.
--cursor.faint — faint cursor.
--cursor.foreground="212" — cursor colour, that iconic 212 💜
--cursor.height=0 — cursor height, 0.
--cursor.italic — italic cursor.
--cursor.margin="0 0" — cursor margin, 0 0.
--cursor.mode="blink" — the cursor mode. Default is blink 👁️
--cursor.padding="0 0" — cursor padding, 0 0.
--cursor.strikethrough — strikethrough cursor.
--cursor.underline — underlined cursor.
--cursor.width=0 — cursor width, 0.
--header.align="left" — header alignment, left.
--header.background="" — header background colour, empty.
--header.bold — bold header.
--header.border-background="" — header border background colour.
--header.border-foreground="" — header border foreground colour.
--header.border="none" — header border style, none.
--header.faint — faint header.
--header.foreground="240" — header colour, 240.
--header.height=0 — header height, 0.
--header.italic — italic header.
--header.margin="0 0" — header margin, 0 0.
--header.padding="0 0" — header padding, 0 0.
--header.strikethrough — strikethrough header.
--header.underline — underlined header.
--header.width=0 — header width, 0.
--header="" — the actual header value. Empty by default.
--padding="0 0" — padding for the whole thing, 0 0.
--password — masks the input characters. For when nobody (including your screen) should see 👀 🔒
--placeholder.align="left" — placeholder alignment, left.
--placeholder.background="" — placeholder background colour, empty.
--placeholder.bold — bold placeholder.
--placeholder.border-background="" — its border background colour.
--placeholder.border-foreground="" — its border foreground colour.
--placeholder.border="none" — its border style, none.
--placeholder.faint — faint placeholder.
--placeholder.foreground="240" — placeholder colour, 240.
--placeholder.height=0 — placeholder height, 0.
--placeholder.italic — italic placeholder.
--placeholder.margin="0 0" — placeholder margin, 0 0.
--placeholder.padding="0 0" — placeholder padding, 0 0.
--placeholder.strikethrough — strikethrough placeholder.
--placeholder.underline — underlined placeholder.
--placeholder.width=0 — placeholder width, 0.
--placeholder="Type something..." — the placeholder text. Default here is Type something... ✍️
--prompt.align="left" — prompt alignment, left.
--prompt.background="" — prompt background colour, empty.
--prompt.bold — bold prompt.
--prompt.border-background="" — prompt border background colour.
--prompt.border-foreground="" — prompt border foreground colour.
--prompt.border="none" — prompt border style, none.
--prompt.faint — faint prompt.
--prompt.foreground="" — prompt colour. Empty default here, not 240 — mind the difference 🧐
--prompt.height=0 — prompt height, 0.
--prompt.italic — italic prompt.
--prompt.margin="0 0" — prompt margin, 0 0.
--prompt.padding="0 0" — prompt padding, 0 0.
--prompt.strikethrough — strikethrough prompt.
--prompt.underline — underlined prompt.
--prompt.width=0 — prompt width, 0.
--prompt="> " — the prompt string. Defaults to > ⭐
--show-help — shows the help keybinds.
--strip-ansi — strips ANSI sequences when reading from STDIN. Yes, again. It's everywhere and we love her 💅
--timeout=0s — timeout until the input aborts. Default 0s.
--value="" — initial value. You can also pass it in via stdin 😌
--width=0 — input width. 0 means it uses the terminal width.

🦋 `join` `<text> ...` `[flags]`

Glues your text together — vertically or horizontally, dealer's choice 🌈

OPTIONS

--align="left" — text alignment, left by default.
--horizontal — joins potentially multi-line strings side by side instead of stacked 🫶
--vertical — stacks (potentially multi-line) strings vertically, like a lil tower of vibes 🗼

🪵 `log <text> ... [flags]`

Logs messages to output. That's it, that's the whole thing — you feed it text, it writes a log line. Very demure, very mindful. 💅

✨ OPTIONS ✨

-o, --file=STRING — log to a file instead of just yeeting it at stdout
-f, --format — formats the message using printf
--formatter="text" — which log formatter to use (default: "text")

Okay so the next chunk is the styling situation, and it comes in themed gangs: key, level, message, prefix, separator, time, value. Each gang has the exact same set of knobs (except key and level skip nothing, they're all identical), so think of this as one lipstick shade in seven different tubes. 💄 Every single one of them is listed below because we do NOT skip things in this house.

🎀 the key crew — how the key part of your structured log looks:

--key.align="left" — text alignment (default "left")
--key.background="" — background color
--key.bold — bold text
--key.border-background="" — border background color
--key.border-foreground="" — border foreground color
--key.border="none" — border style (default "none", so, no border bestie)
--key.faint — faint text
--key.foreground="" — foreground color
--key.height=0 — text height
--key.italic — italicize text
--key.margin="0 0" — text margin
--key.padding="0 0" — text padding
--key.strikethrough — ~~strikethrough~~ text
--key.underline — underline text
--key.width=0 — text width

🌸 the level crew — same energy, now for the log level:

--level.align="left" — text alignment
--level.background="" — background color
--level.bold — bold text
--level.border-background="" — border background color
--level.border-foreground="" — border foreground color
--level.border="none" — border style
--level.faint — faint text
--level.foreground="" — foreground color
--level.height=0 — text height
--level.italic — italicize text
--level.margin="0 0" — text margin
--level.padding="0 0" — text padding
--level.strikethrough — strikethrough text
--level.underline — underline text
--level.width=0 — text width
-l, --level="none" — the log level to use (default "none")

🦋 the message crew — for the actual words you're saying:

--message.align="left" — text alignment
--message.background="" — background color
--message.bold — bold text
--message.border-background="" — border background color
--message.border-foreground="" — border foreground color
--message.border="none" — border style
--message.faint — faint text
--message.foreground="" — foreground color
--message.height=0 — text height
--message.italic — italicize text
--message.margin="0 0" — text margin
--message.padding="0 0" — text padding
--message.strikethrough — strikethrough text
--message.underline — underline text
--message.width=0 — text width
--min-level="" — minimal level to show (default is empty, so everything shows up, no gatekeeping 🚪)

🧚 the prefix crew — the little thing that goes before the message:

--prefix.align="left" — text alignment
--prefix.background="" — background color
--prefix.bold — bold text
--prefix.border-background="" — border background color
--prefix.border-foreground="" — border foreground color
--prefix.border="none" — border style
--prefix.faint — faint text
--prefix.foreground="" — foreground color
--prefix.height=0 — text height
--prefix.italic — italicize text
--prefix.margin="0 0" — text margin
--prefix.padding="0 0" — text padding
--prefix.strikethrough — strikethrough text
--prefix.underline — underline text
--prefix.width=0 — text width
--prefix=STRING — prefix to print before the message

🍓 the separator crew — the divider between bits:

--separator.align="left" — text alignment
--separator.background="" — background color
--separator.bold — bold text
--separator.border-background="" — border background color
--separator.border-foreground="" — border foreground color
--separator.border="none" — border style
--separator.faint — faint text
--separator.foreground="" — foreground color
--separator.height=0 — text height
--separator.italic — italicize text
--separator.margin="0 0" — text margin
--separator.padding="0 0" — text padding
--separator.strikethrough — strikethrough text
--separator.underline — underline text
--separator.width=0 — text width
-s, --structured — use structured logging (keys and values, the whole organized moment 👑

💜 the time crew — timestamp aesthetics:

--time.align="left" — text alignment
--time.background="" — background color
--time.bold — bold text
--time.border-background="" — border background color
--time.border-foreground="" — border foreground color
--time.border="none" — border style
--time.faint — faint text
--time.foreground="" — foreground color
--time.height=0 — text height
--time.italic — italicize text
--time.margin="0 0" — text margin
--time.padding="0 0" — text padding
--time.strikethrough — strikethrough text
--time.underline — underline text
--time.width=0 — text width
-t, --time="" — the time format to use (kitchen, layout, ansic, rfc822, etc…)

⭐ the value crew — closing out the styling gangs:

--value.align="left" — text alignment
--value.background="" — background color
--value.bold — bold text
--value.border-background="" — border background color
--value.border-foreground="" — border foreground color
--value.border="none" — border style
--value.faint — faint text
--value.foreground="" — foreground color
--value.height=0 — text height
--value.italic — italicize text
--value.margin="0 0" — text margin
--value.padding="0 0" — text padding
--value.strikethrough — strikethrough text
--value.underline — underline text
--value.width=0 — text width

📜 `pager [<content>] [flags]`

Scrolls through a file. Cozy little reading nook energy, but make it terminal. 🛋️

✨ OPTIONS ✨

--align="left" — text alignment
--background="" — background color
--bold — bold text
--border-background="" — border background color
--border-foreground="212" — border foreground color (default "212", a very cute pink-ish number bestie)
--border="rounded" — border style (default "rounded", obviously, we're soft here)
--faint — faint text
--foreground="" — foreground color
--height=0 — text height

🙈 the help crew — for the help text itself:

--help.align="left" — text alignment
--help.background="" — background color
--help.bold — bold text
--help.border-background="" — border background color
--help.border-foreground="" — border foreground color
--help.border="none" — border style
--help.faint — faint text
--help.foreground="241" — foreground color (default "241")
--help.height=0 — text height
--help.italic — italicize text
--help.margin="0 0" — text margin
--help.padding="0 0" — text padding
--help.strikethrough — strikethrough text
--help.underline — underline text
--help.width=0 — text width
--italic — italicize text

🔢 the line-number crew — the numbers down the side:

--line-number.align="left" — text alignment
--line-number.background="" — background color
--line-number.bold — bold text
--line-number.border-background="" — border background color
--line-number.border-foreground="" — border foreground color
--line-number.border="none" — border style
--line-number.faint — faint text
--line-number.foreground="237" — foreground color (default "237")
--line-number.height=0 — text height
--line-number.italic — italicize text
--line-number.margin="0 0" — text margin
--line-number.padding="0 0" — text padding
--line-number.strikethrough — strikethrough text
--line-number.underline — underline text
--line-number.width=0 — text width
--margin="0 0" — text margin

🔥 the match-highlight crew — for when your search hits, and it HITS:

--match-highlight.align="left" — text alignment
--match-highlight.background="225" — background color (default "225")
--match-highlight.bold — bold text
--match-highlight.border-background="" — border background color
--match-highlight.border-foreground="" — border foreground color
--match-highlight.border="none" — border style
--match-highlight.faint — faint text
--match-highlight.foreground="235" — foreground color (default "235")
--match-highlight.height=0 — text height
--match-highlight.italic — italicize text
--match-highlight.margin="0 0" — text margin
--match-highlight.padding="0 0" — text padding
--match-highlight.strikethrough — strikethrough text
--match-highlight.underline — underline text
--match-highlight.width=0 — text width

🔍 and the match crew — the plain, un-highlighted matches:

--match.align="left" — text alignment
--match.background="" — background color
--match.bold — bold text
--match.border-background="" — border background color
--match.border-foreground="" — border foreground color
--match.border="none" — border style for the match highlight 💅
--match.faint — faint text for matches
--match.foreground="212" — foreground color of the match (default 212, she's got taste ✨)
--match.height=0 — text height
--match.italic — italicize the match text
--match.margin="0 0" — text margin
--match.padding="0 0" — text padding
--match.strikethrough — strikethrough text
--match.underline — underline text
--match.width=0 — text width
--padding="0 1" — text padding, defaulting to "0 1" 🎀
--show-line-numbers — show line numbers, lowkey essential ngl
--soft-wrap — soft wrap those long lines 🦋
--strikethrough — strikethrough text
--timeout=0s — timeout until command exits
--underline — underline text
--width=0 — text width

🌀 `spin` — the "we're working on it bestie" command

spin <command> ... [flags]

Displays a spinner while running a command. It's giving main character energy while your build chugs along in the background 💀

✨ OPTIONS ✨

-a, --align="left" — alignment of the spinner with regard to the title, default "left"
--padding="0 0" — padding
--show-error — show the output of the command only if the command fails 🙈
--show-output — show or pipe the output of the command during execution (shows both STDOUT and STDERR, so you get the whole picture)
--show-stderr — show STDERR errput (yes, "errput", that's what it says, iconic typo honestly)
--show-stdout — show STDOUT output
--spinner.align="left" — text alignment for the spinner itself
--spinner.background="" — background color
--spinner.bold — bold text
--spinner.border-background="" — border background color
--spinner.border-foreground="" — border foreground color
--spinner.border="none" — border style
--spinner.faint — faint text
--spinner.foreground="212" — foreground color, default "212" 🍓
--spinner.height=0 — text height
--spinner.italic — italicize text
--spinner.margin="0 0" — text margin
--spinner.padding="0 0" — text padding
--spinner.strikethrough — strikethrough text
--spinner.underline — underline text
--spinner.width=0 — text width
-s, --spinner="dot" — spinner type, default "dot" (a literal dot spinning, slay)
--timeout=0s — timeout until the spin command aborts
--title.align="left" — text alignment for the title
--title.background="" — background color
--title.bold — bold text
--title.border-background="" — border background color
--title.border-foreground="" — border foreground color
--title.border="none" — border style
--title.faint — faint text
--title.foreground="" — foreground color
--title.height=0 — text height
--title.italic — italicize text
--title.margin="0 0" — text margin
--title.padding="0 0" — text padding
--title.strikethrough — strikethrough text
--title.underline — underline text
--title.width=0 — text width
--title="Loading..." — the text you show the user while spinning, default "Loading..." 🫶

🎨 `style` — make your text pretty

style [<text> ...] [flags]

Apply coloring, borders, spacing to text. This is THE glow-up command, no cap 💅✨

✨ OPTIONS ✨

--align="left" — text alignment
--background="" — background color
--bold — bold text
--border-background="" — border background color
--border-foreground="" — border foreground color
--border="none" — border style
--faint — faint text
--foreground="" — foreground color
--height=0 — text height
--italic — italicize text
--margin="0 0" — text margin
--padding="0 0" — text padding
--strikethrough — strikethrough text
--strip-ansi — strip ANSI sequences when reading from STDIN 🧼
--trim — trim whitespaces on every input line
--underline — underline text
--width=0 — text width

📊 `table` — render a table of data

table [flags]

Render a table of data. Data girlies rise up 🌈

✨ OPTIONS ✨

--border.align="left" — text alignment
--border.background="" — background color
--border.bold — bold text
--border.border-background="" — border background color
--border.border-foreground="" — border foreground color
--border.border="none" — border style
--border.faint — faint text
--border.foreground="" — foreground color
--border.height=0 — text height
--border.italic — italicize text
--border.margin="0 0" — text margin
--border.padding="0 0" — text padding
--border.strikethrough — strikethrough text
--border.underline — underline text
--border.width=0 — text width
-b, --border="rounded" — border style, default "rounded" (rounded corners are objectively superior, I don't make the rules) 🎀
--cell.align="left" — text alignment
--cell.background="" — background color
--cell.bold — bold text
--cell.border-background="" — border background color
--cell.border-foreground="" — border foreground color
--cell.border="none" — border style
--cell.faint — faint text
--cell.foreground="" — foreground color
--cell.height=0 — text height
--cell.italic — italicize text
--cell.margin="0 0" — text margin
--cell.padding="0 0" — text padding
--cell.strikethrough — strikethrough text
--cell.underline — underline text
--cell.width=0 — text width
-c, --columns=COLUMNS,... — column names
--fields-per-record=0 — sets the number of expected fields per record
-f, --file="" — file path
--header.align="left" — text alignment
--header.background="" — background color
--header.bold — bold text
--header.border-background="" — border background color
--header.border-foreground="" — border foreground color
--header.border="none" — border style
--header.faint — faint text
--header.foreground="" — foreground color
--header.height=0 — text height
--header.italic — italicize text
--header.margin="0 0" — text margin
--header.padding="0 0" — text padding
--header.strikethrough — strikethrough text
--header.underline — underline text
--header.width=0 — text width
--height=0 — table height
--hide-count — hide item count on help keybinds
--lazy-quotes — if LazyQuotes is true, a quote may appear in an unquoted field and a non-doubled quote may appear in a quoted field (that's the whole description, bestie, take it verbatim)
--padding="0 0" — padding
-p, --print — static print
-r, --return-column=0 — which column number should be returned instead of whole row as string. Default=0 returns whole Row 🫶
--selected.align="left" — text alignment
--selected.background="" — background color
--selected.bold — bold text
--selected.border-background="" — border background color
--selected.border-foreground="" — border foreground color
--selected.border="none" — border style
--selected.faint — faint text
--selected.foreground="212" — foreground color, default "212" 🍓
--selected.height=0 — text height
--selected.italic — italicize text
--selected.margin="0 0" — text margin
--selected.padding="0 0" — text padding
--selected.strikethrough — strikethrough text
--selected.underline — underline text
--selected.width=0 — text width
-s, --separator="," — row separator, default ","
--show-help — show help keybinds
--timeout=0s — timeout until choose returns selected element
-w, --widths=WIDTHS,... — column widths

🏷️ `version-check` — semver vibes

version-check <constraint> [flags]

Semver check current gum version. Like a vibe check but for version numbers 💀

✍️ `write` — prompt for long-form text

write [flags]

Prompt for long-form text. Essay mode activated, bestie 📝

✨ OPTIONS ✨

--base.align="left" — text alignment
--base.background="" — background color
--base.bold — bold text
--base.border-background="" — border background color
--base.border-foreground="" — border foreground color
--base.border="none" — border style
--base.faint — faint text
--base.foreground="" — foreground color
--base.height=0 — text height
--base.italic — italicize text
--base.margin="0 0" — text margin
--base.padding="0 0" — text padding
--base.strikethrough — strikethrough text
--base.underline — underline text
--base.width=0 — text width
--char-limit=0 — maximum value length (0 for no limit, so 0 means go off queen)
--cursor-line-number.align="left" — text alignment
--cursor-line-number.background="" — background color
--cursor-line-number.bold — bold text
--cursor-line-number.border-background="" — border background color
--cursor-line-number.border-foreground="" — border foreground color
--cursor-line-number.border="none" — border style
--cursor-line-number.faint — faint text
--cursor-line-number.foreground="7" — foreground colour, default 7 🎨
--cursor-line-number.height=0 — text height, default 0
--cursor-line-number.italic — italicize the text 🦋
--cursor-line-number.margin="0 0" — text margin, default 0 0
--cursor-line-number.padding="0 0" — text padding, default 0 0
--cursor-line-number.strikethrough — strikethrough text 💀
--cursor-line-number.underline — underline text
--cursor-line-number.width=0 — text width, default 0

okay next up, the cursor-line bundle — the whole-line version of that vibe 🫶

--cursor-line.align="left" — text alignment, default left
--cursor-line.background="" — background colour, default empty
--cursor-line.bold — bold text 🔥
--cursor-line.border-background="" — border background colour, default empty
--cursor-line.border-foreground="" — border foreground colour, default empty
--cursor-line.border="none" — border style, default none
--cursor-line.faint — faint text
--cursor-line.foreground="" — foreground colour, default empty
--cursor-line.height=0 — text height, default 0
--cursor-line.italic — italicize text
--cursor-line.margin="0 0" — text margin, default 0 0
--cursor-line.padding="0 0" — text padding, default 0 0
--cursor-line.strikethrough — strikethrough text
--cursor-line.underline — underline text
--cursor-line.width=0 — text width, default 0

and now the actual cursor itself, main character energy 👑

--cursor.align="left" — text alignment, default left
--cursor.background="" — background colour, default empty
--cursor.bold — bold text
--cursor.border-background="" — border background colour, default empty
--cursor.border-foreground="" — border foreground colour, default empty
--cursor.border="none" — border style, default none
--cursor.faint — faint text
--cursor.foreground="212" — foreground colour, default 212 💅
--cursor.height=0 — text height, default 0
--cursor.italic — italicize text
--cursor.margin="0 0" — text margin, default 0 0
--cursor.mode="blink" — cursor mode, default blink ✨
**--cursor.padding="0 0"** — text padding, default 0 0`
--cursor.strikethrough — strikethrough text
--cursor.underline — underline text
--cursor.width=0 — text width, default 0

end-of-buffer squad, for when you've scrolled all the way down 😭

--end-of-buffer.align="left" — text alignment, default left
--end-of-buffer.background="" — background colour, default empty
--end-of-buffer.bold — bold text
--end-of-buffer.border-background="" — border background colour, default empty
--end-of-buffer.border-foreground="" — border foreground colour, default empty
--end-of-buffer.border="none" — border style, default none
--end-of-buffer.faint — faint text
--end-of-buffer.foreground="0" — foreground colour, default 0
--end-of-buffer.height=0 — text height, default 0
--end-of-buffer.italic — italicize text
--end-of-buffer.margin="0 0" — text margin, default 0 0
--end-of-buffer.padding="0 0" — text padding, default 0 0
--end-of-buffer.strikethrough — strikethrough text
--end-of-buffer.underline — underline text
--end-of-buffer.width=0 — text width, default 0

header styling, because first impressions >>> 🌸

--header.align="left" — text alignment, default left
--header.background="" — background colour, default empty
--header.bold — bold text
--header.border-background="" — border background colour, default empty
--header.border-foreground="" — border foreground colour, default empty
--header.border="none" — border style, default none
--header.faint — faint text
--header.foreground="240" — foreground colour, default 240
--header.height=0 — text height, default 0
--header.italic — italicize text
--header.margin="0 0" — text margin, default 0 0
--header.padding="0 0" — text padding, default 0 0
--header.strikethrough — strikethrough text
--header.underline — underline text
--header.width=0 — text width, default 0
--header="" — the actual header value, default empty 🎀
--height=5 — text area height, default 5
--line-number.align="left" — text alignment, default left
--line-number.background="" — background colour, default empty
--line-number.bold — bold text
--line-number.border-background="" — border background colour, default empty
--line-number.border-foreground="" — border foreground colour, default empty
--line-number.border="none" — border style, default none
--line-number.faint — faint text
--line-number.foreground="7" — foreground colour, default 7
--line-number.height=0 — text height, default 0
--line-number.italic — italicize text
--line-number.margin="0 0" — text margin, default 0 0
--line-number.padding="0 0" — text padding, default 0 0
--line-number.strikethrough — strikethrough text
--line-number.underline — underline text
--line-number.width=0 — text width, default 0
--max-lines=0 — maximum number of lines; 0 means no limit 🚫
--padding="0 0" — padding, default 0 0
--placeholder.align="left" — text alignment, default left
--placeholder.background="" — background colour, default empty
--placeholder.bold — bold text
--placeholder.border-background="" — border background colour, default empty
--placeholder.border-foreground="" — border foreground colour, default empty
--placeholder.border="none" — border style, default none
--placeholder.faint — faint text
--placeholder.foreground="240" — foreground colour, default 240
--placeholder.height=0 — text height, default 0
--placeholder.italic — italicize text
--placeholder.margin="0 0" — text margin, default 0 0
--placeholder.padding="0 0" — text padding, default 0 0
--placeholder.strikethrough — strikethrough text
--placeholder.underline — underline text
--placeholder.width=0 — text width, default 0
--placeholder="Write something..." — the placeholder value itself, default Write something... ✍️
--prompt.align="left" — text alignment, default left
--prompt.background="" — background colour, default empty
--prompt.bold — bold text
--prompt.border-background="" — border background colour, default empty
--prompt.border-foreground="" — border foreground colour, default empty
--prompt.border="none" — border style, default none
--prompt.faint — faint text
--prompt.foreground="7" — foreground colour, default 7
--prompt.height=0 — text height, default 0
--prompt.italic — italicize text
--prompt.margin="0 0" — text margin, default 0 0
--prompt.padding="0 0" — text padding, default 0 0
--prompt.strikethrough — strikethrough text
--prompt.underline — underline text
--prompt.width=0 — text width, default 0
--prompt="┃ " — the prompt to display, default ┃ 🫶
--show-cursor-line — show the cursor line 👀
--show-help — show help key binds ⌨️
--show-line-numbers — show line numbers 🔢
--strip-ansi — strip ANSI sequences when reading from STDIN 🧼
--timeout=0s — timeout until choose returns the selected element, default 0s ⏳
--value="" — initial value (and yes, it can be passed via stdin), default empty 💜
--width=0 — text area width; 0 means terminal width, default 0 📐

💖 COPYRIGHT 💖

Released under MIT license.

okay that's the whole page bestie, you're officially a gum scholar 🎓✨ this beauty is gum, stamped 2026-09-24, and filed under GUM(1) — go forth and make your terminal gorgeous 💅🌈

📦 where this page comes from

arch rolling: gum 2.0.2-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

GUM(1)

💅 GUM 💅

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🎀 OPTIONS 🎀

🌈 COMMANDS 🌈

🌟 choose [<options> ...] [flags]

💖 OPTIONS 💖

🌟 confirm [<prompt>] [flags]

💖 OPTIONS 💖

🌟 file [<path>] [flags]

💖 OPTIONS 💖

🦋 filter [<options> ...] [flags]

✨ OPTIONS ✨

🎀 format [<template> ...] [flags]

OPTIONS

🌸 input [flags]

OPTIONS

🦋 join <text> ... [flags]

OPTIONS

🪵 log <text> ... [flags]

✨ OPTIONS ✨

📜 pager [<content>] [flags]

✨ OPTIONS ✨

🌀 spin — the "we're working on it bestie" command

✨ OPTIONS ✨

🎨 style — make your text pretty

✨ OPTIONS ✨

📊 table — render a table of data

✨ OPTIONS ✨

🏷️ version-check — semver vibes

✍️ write — prompt for long-form text

✨ OPTIONS ✨

💖 COPYRIGHT 💖

🌟 `choose [<options> ...] [flags]`

🌟 `confirm [<prompt>] [flags]`

🌟 `file [<path>] [flags]`

🦋 `filter` [<options> ...] [flags]

🎀 `format` `[<template> ...]` `[flags]`

🌸 `input` `[flags]`

🦋 `join` `<text> ...` `[flags]`

🪵 `log <text> ... [flags]`

📜 `pager [<content>] [flags]`

🌀 `spin` — the "we're working on it bestie" command

🎨 `style` — make your text pretty

📊 `table` — render a table of data

🏷️ `version-check` — semver vibes

✍️ `write` — prompt for long-form text