gum-wrapper 0.3.0

A typed Python wrapper for the gum CLI tool.

gum-py

A typed Python wrapper for the gum CLI tool.

Build glamorous interactive shell scripts from Python — without writing a line of Go.

Requirements

• Python 3.9+
• gum on your $PATH
• pydantic ≥ 2.0

Installation

pip install gum-py

Install gum itself via your package manager:

brew install gum          # macOS / Linux
winget install charmbracelet.gum  # Windows

Quick start

from gum import Gum

with Gum() as g:
    kind = g.choose(
        items=["fix", "feat", "docs", "chore"],
        header="Commit type",
    )
    scope   = g.input(placeholder="scope (optional)")
    summary = g.input(placeholder="Short summary", width=72)
    body    = g.write(placeholder="Extended description  (ctrl+d to finish)")

    if g.confirm(prompt="Commit?", default=False):
        import subprocess
        msg = f"{kind[0]}{f'({scope})' if scope else ''}: {summary}"
        subprocess.run(["git", "commit", "-m", msg, "-m", body])

Run the built-in demo:

python -m gum
# or, after pip install:
gum-demo

Two calling styles

Every method accepts either inline kwargs (a config model is built internally) or an explicit config object (validated before the call):

g = Gum()

# Style 1 — inline kwargs
selected = g.choose(items=["a", "b", "c"], height=5)

# Style 2 — config object
from gum import ChooseConfig
cfg = ChooseConfig(items=["a", "b", "c"], height=5)
selected = g.choose(cfg)

Styling

Pass a StyleOptions instance to any *_style parameter:

from gum import Gum, StyleOptions, BorderStyle, Align

g = Gum()
box = g.style(
    texts=["Bubble Gum (1¢)", "So sweet and so fresh!"],
    foreground="212",
    border=BorderStyle.DOUBLE,
    border_foreground="212",
    align=Align.CENTER,
    width=50,
    margin="1 2",
    padding="2 4",
)
print(box)

Environment variables

gum supports GUM_* environment variables. Pass them via the env parameter to have them apply to every call made through that instance:

g = Gum(env={"GUM_INPUT_CURSOR_FOREGROUND": "#FF0"})

Explicit flags set through config objects always take precedence over env vars.

Commands

Method	gum command	Returns
choose()	gum choose	list[str]
confirm()	gum confirm	bool
input()	gum input	str
write()	gum write	str
filter()	gum filter	list[str]
spin()	gum spin	str
style()	gum style	str
join()	gum join	str
format()	gum format	str
log()	gum log	None
file()	gum file	str
pager()	gum pager	None
table()	gum table	str

Error handling

from gum import Gum, GumNotFoundError, GumCommandError

try:
    g = Gum()
    name = g.input(placeholder="Your name")
except GumNotFoundError:
    print("gum is not installed — see https://github.com/charmbracelet/gum")
except GumCommandError as e:
    print(f"gum exited {e.returncode}: {e.stderr}")

License

MIT