← All libraries

CandyShell

🐚 CandyShell

Composer-installable CLI of TUI primitives

port of gum cli shell-script one-shot

13 subcommands — choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write. Drop into a shell script and instantly get a Charm-quality interactive UX.

Install

composer require candycore/candy-shell

Quickstart

# Apply styling.
candyshell style --foreground "#ff5f87" --bold "Hello, candy!"

# Pick one item.
choice=$(candyshell choose Pizza Burger Salad)

# Read a single line.
name=$(candyshell input --placeholder "Your name?")

# Confirm a destructive action.
candyshell confirm "Really delete $file?" && rm "$file"

# Show a spinner while running a command.
candyshell spin --title "Building..." -- make build

# Fuzzy-filter a list.
git branch | candyshell filter

What's in the box

styleApply Sprinkles styling to argv (or stdin) and print.
choosePick one item from a list; prints the selection to stdout.
confirmYes/no — exit code 0 on yes, 1 on no.
filterFuzzy-filter over stdin lines.
input / writeSingle-line / multi-line text input.
fileFile picker — print the selected path.
formatRender Markdown via CandyShine.
pagerScroll long input through a SugarBits Viewport.
spinShow a spinner while running an external command.
tableRender a CSV / TSV table with rounded borders.
logLeveled logging output (debug / info / warn / error / fatal).
joinConcatenate styled strings horizontally / vertically.

Source & demos

Try the quickstart →

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.

choose

choose

Pick one item from a list.
confirm

confirm

Yes/no with exit-code semantics.
input

input

Read a single line.
write

write

Multi-line text editor.
file

file

Pick a file path.
filter

filter

Fuzzy filter over stdin.
format

format

Render Markdown via CandyShine.
style

style

Apply foreground / bold to argv.
table

table

Render CSV with rounded borders.
pager

pager

Scroll long input.
log

log

Leveled logging output.
spin

spin

Spinner while running a command.
join

join

Concatenate styled chunks.