MOMA / API REFERENCE

Moma Terminal components

Complete visual and functional reference for the Moma Bash library. Every public function is listed below with its signature, purpose, and terminal output where applicable.

Previewbash <(curl -fsSL https://raw.githubusercontent.com/Mgldvd/moma/master/dist/moma) preview

Loadsource <(curl -fsSL https://raw.githubusercontent.com/Mgldvd/moma/master/dist/moma)moma msg "Ready" --success

Installmkdir -p "$HOME/.local/bin"curl -fsSL https://raw.githubusercontent.com/Mgldvd/moma/master/dist/moma -o "$HOME/.local/bin/moma"chmod 0755 "$HOME/.local/bin/moma"

The moma <command> syntax works the same way whether the library is sourced or the executable is installed. Direct moma-* functions (for example moma-msg) remain available after sourcing, for backward compatibility with existing scripts.

Semantic states

--success, --error, --warning, and --info aren't colors of their own - each just resolves to one of the named colors below.

--success

✔ green

--error

✖ red

--warning

! yellow

--info

→ cyan

Named colors

Pass any of these to --color <name> on every component.cyan is the default when --color is left out entirely.

black

red

green

yellow

blue

purple

cyandefault

white

pink

gray

ASCII heading component

header

Three-line Pagga text for a prominent script or workflow identity, with one blank line above, two below, and no left indent by default.

moma header "TEXT" [--color color] [--margin-top number] [--margin-bottom number] [--margin-left number] [--no-color]

Bash examples

moma header "Moma"

moma header "Deploy 2026" --color cyan --margin-bottom 1

moma header "Build ready" --margin-top 0 --margin-bottom 0 --margin-left 2 --no-color

Output

Heading component

title

Primary identity block for the beginning of a script or major workflow.

moma title "Moma" "Terminal UI library" [--success|--error|--warning|--info] [--primary color] [--accent color] [--icon char] [--no-icon] [--border mirror|line|open] [--width number] [--max-width number]

Bash examples

moma title "Moma" "Terminal UI library"

moma title "Deploy" "Production" --primary cyan

moma title "Backup" "Nightly job" --accent yellow --min-width 48

moma title "Moma" "Terminal UI library" --success --border line

moma title "Moma" "Terminal UI library" --no-icon --border open

Output

Heading component

title-sub

Secondary heading for stages nested inside the main workflow.

moma title-sub "Deployment" "Production environment" [--success|--error|--warning|--info] [--color color] [--icon char] [--no-icon] [--border mirror|line|open] [--width number] [--max-width number]

Bash examples

moma title-sub "Dependencies" "Installing packages"

moma title-sub "Deploy" "Production" --color cyan

moma title-sub "Tests" --message "Running suite" --min-width 42

moma title-sub "Dependencies" "Installing packages" --border mirror

Output

Heading component

sub-title

Rule-first secondary heading: the same marker/padding line as moma-title-sub, but with the rule printed above the text instead of below it, and no closing row.

moma sub-title "Moma" "Terminal UI library" [--success|--error|--warning|--info] [--color color] [--icon char] [--no-icon] [--border mirror|line|open] [--min-width number] [--width number] [--max-width number]

Bash examples

moma sub-title "Moma" "Terminal UI library"

moma sub-title "Moma" "Terminal UI library" --no-icon --border open

moma sub-title "Moma" "Terminal UI library" --border line

Output

Section component

section

Strong separator that gives semantic context to the content that follows.

moma section "Dependencies ready" --success

Bash examples

moma section "Dependencies ready" --success

moma section "Configuration failed" --error

moma section "Next step" --info --icon "→"

Output

Message component

msg

Compact feedback with semantic defaults or custom color and icon overrides.

moma msg "Package installed" --success [--color value] [--icon value]

Bash examples

moma msg "Package installed" --success

moma msg "Connection refused" --error

moma msg "Downloading metadata" --color cyan --icon "→"

Output

Simple message

msg-simple

A quiet message with only a dot marker and no semantic icon.

moma msg-simple "Package installed" [--success|--error|--warning|--info] [--color value]

Bash examples

moma msg-simple "Package installed"

moma msg-simple "Package installation failed" --error

moma msg-simple "Queued" --color yellow --marker "•"

Output

List component

list

An unordered terminal list with a consistent marker for every item.

moma list "Clone repository" "Install dependencies" [--success|--error|--warning|--info]

Bash examples

moma list "Clone repository" "Install dependencies" "Start application"

moma list "Database ready" "Cache ready" --success

moma list "Review logs" "Retry deployment" --marker "→" --color yellow

Output

Notice component

box

Framed notice with automatic, fixed, or maximum width. Long content wraps inside the border.

moma box "Configuration is ready." --success [--width number] [--max-width number]

Bash examples

moma box "Configuration is ready." --success

moma box "Review the deployment settings." --warning --width 48

moma box "A long notice wraps inside its border." --info --max-width 32

Output

Content block component

resume

Titled, colored content block for grouping related information, such as a résumé section or a categorized reference list. Rows come from repeated --item (a bold term next to a muted description, aligned as a column) and --text (a plain line), interleaved in the order given. The title is a single open line by default; setting an icon switches to a boxed header, mirroring moma-title's own marker conventions.

moma resume --title "<text>" [--item "term" "description"]... [--text "line"]... [--success|--error|--warning|--info] [--color color] [--icon char] [--no-icon] [--border mirror|line|open] [--width number] [--max-width number] [--no-color]

Bash examples

moma resume --title "Shells" --color blue --item "Bash" "GNU command shell." --item "Zsh" "Interactive shell with completion."

moma resume --title "Summary" --text "All checks passed." --text "No manual follow-up required."

moma resume --title "Review" --warning --item "Environment" "production" --text "Confirm the target before deploying."

moma resume --title "Moma Terminal UI library" --no-icon --border open --text "element 1" --text "element 2"

Output

Rule component

divider

Marker-led horizontal rule, for separating sections without a full heading. Uses — (em dash) instead of the ─ box-drawing character elsewhere in Moma, and has no left box edge, only an optional bare ┌/└ pair framing the rule above and below.

moma divider [--success|--error|--warning|--info] [--color color] [--icon char] [--no-icon] [--border mirror|line|open] [--min-width number] [--width number] [--max-width number] [--no-color]

Bash examples

moma divider

moma divider --success --border line

moma divider --icon "⏻" --border line

Output

Label component

label

Print an input-style decorated label with automatic width, semantic color support, and one blank line below it.

moma label "TEXT HERE" [--width number] [--min-width number] [--max-width number] [--color color] [--icon symbol] [--edge top|bottom] [--border line|open]

Bash examples

moma label "PROJECT NAME"

moma label "DEPLOYMENT" --success

moma label "NOTES" --width 52 --color cyan --icon "→"

moma label "END OF REPORT" --edge bottom --border open

Output

Input component

input

Display or read a field with placeholders, validation, secret masking, and one blank line below each interactive value.

moma input --title "Project name" --read --required [--secret] [--mask symbol] [--default value] [--width number] [--max-width number]

Bash examples

moma input --title "Project name" --placeholder "my-project"

project="$(moma input --title "Project name" --read --required --trim)"

password="$(moma input --title "Password" --read --secret --required)"

Output

Prompt component

prompt

Free-text prompt with moma-title-sub's own marker + underline look instead of moma-input's boxed field - the two share the same read, validation, and secret-masking machinery, and differ only in how the question is drawn.

moma prompt "<question>" [--success|--error|--warning|--info] [--color color] [--icon char] [--no-icon] [--border mirror|line|open] [--cursor char] [--default value] [--secret] [--mask char] [--required] [--trim] [--min-width number] [--width number] [--max-width number]

Bash examples

answer="$(moma prompt "Continue with the installation?")"

answer="$(moma prompt "Deploy now?" --default "yes")"

token="$(moma prompt "API token" --secret --required)"

Output

Confirmation select

confirm

Select Yes or No with the arrow keys, Enter, or the y and n shortcuts. A successful answer leaves one blank line below the controls.

moma confirm "Create this project?" [--default yes|no] [--answer yes|no]

Bash examples

moma confirm "Create this project?" --default yes

moma confirm "Delete the cache?" --answer no

if moma confirm "Deploy now?"; then
  moma msg "Deploying" --info
fi

Output

Select component

select

Select one value with the arrow keys, return it through standard output, and leave one blank line below the controls. Also available as moma single-select for existing scripts.

moma select "Development" "Staging" "Production" [--title text] [--initial number]

Bash examples

environment="$(moma select "Development" "Staging" "Production" --title "Environment")"

environment="$(moma select "Development" "Staging" "Production" --choose 2)"

region="$(moma select "US" "EU" "APAC" --title "Region" --initial 2 --color cyan)"

Output

Select component

select-groups

Select one value organized under named, non-selectable group headings. Option numbers are one-based, count only options, and follow visual order across every group.

moma single-select-groups --title text (--group name --option value...)... [--initial number] [--choose number]

Bash examples

action="$(moma single-select-groups --title "Features" --group "Docker" --option "Up" --option "Down" --option "Stop" --group "npm" --option "install" --option "run dev" --option "run deploy")"

action="$(moma single-select-groups --title "Features" --group "Docker" --option "Up" --option "Down" --option "Stop" --group "npm" --option "install" --option "run dev" --option "run deploy" --choose 4)"

Output

Multiple select

multi-select

Toggle multiple values below a decorated Moma heading and return every selection on its own line.

moma multi-select "Docker" "CI" "Tests" [--selected 1,3] [--required] [--checkbox box|brackets]

Bash examples

features="$(moma multi-select "Docker" "CI" "Tests" --title "Features")"

features="$(moma multi-select "Docker" "CI" "Tests" --choose 1,3)"

features="$(moma multi-select "Docker" "CI" "Tests" --selected 1,2 --required)"

features="$(moma multi-select "Docker" "CI" "Tests" --checkbox brackets)"

Output

Multiple select

multi-select-groups

Toggle multiple values organized under named, non-selectable group headings and return every selection on its own line, in original visual order.

moma multi-select-groups --title text (--group name --option value...)... [--selected numbers] [--choose numbers] [--required] [--checkbox box|brackets]

Bash examples

countries="$(moma multi-select-groups --title "Features" --group "North America" --option "United States" --option "Canada" --option "Mexico" --group "South America" --option "Colombia" --option "Argentina" --option "Peru")"

countries="$(moma multi-select-groups --title "Features" --group "North America" --option "United States" --option "Canada" --option "Mexico" --group "South America" --option "Colombia" --option "Argentina" --option "Peru" --choose 1,3 --required)"

Output

Activity component

rabbit

Branded activity and completion feedback using Moma's rabbit signature.

moma rabbit "Preparing workspace" --info

Bash examples

moma rabbit "Preparing workspace" --info

moma rabbit "Deployment complete" --success

moma rabbit "Build needs attention" --warning --icon "!"

Output

Process helper

spinner

Display progress while a process is active, then print semantic completion feedback.

moma spinner pid ["message"] [--delay seconds]

Bash examples

sleep 2 &
moma spinner "$!" "Waiting"

backup_database &
moma spinner --pid "$!" --message "Backing up"

build_project &
moma spinner "$!" "Building" --delay 0.05

Output

Dependency helper

command-check

Check whether every requested executable is available and return a useful status.

moma command-check bash curl git [--quiet]

Bash examples

moma command-check bash curl git

moma command-check docker --quiet

if ! moma command-check git; then
  exit 1
fi

Output

Release helper

update

Download, validate, and atomically replace an executable Moma installation.

moma update

Bash examples

moma update

Output

  ▪   moma: updated successfully

Release helper

version

Print the version embedded in the installed Moma executable.

moma version

Bash examples

moma version

Output

Documentation helper

preview

Show a categorized terminal, Markdown, or browser preview of every component, without leaving the CLI.

moma preview [md|web]

Bash examples

moma preview

moma preview md

moma preview web

Output

  ────────────────────────────────────────────────────────────────
    MOMA  COMPONENT GALLERY
    Visual reference for the public terminal UI API
  ────────────────────────────────────────────────────────────────

    Legend  ● success  ● error  ● warning  ● info
    ⋮

Documentation helper

help

Print full usage: every command, its description, and the global flags.

moma help

Bash examples

moma help

moma --help

moma -h

Output

  Moma - terminal UI components for Bash

  Usage:
    moma <command> [arguments] [options]
    source dist/moma

  Commands:
    header                 Print a Pagga ASCII heading.
    msg                     Print a styled message.
    select                  Select one value (alias for single-select).
    ⋮  every command and helper, one row each

  Example:
    moma msg "Ready" --success

Component commands

Call any visual component without sourcing the library.

moma title | title-sub | sub-title | section | msg | msg-simple | list | box | resume | divider | label | input | prompt | select | single-select | single-select-groups | multi-select | multi-select-groups | rabbit

Helper commands

Run confirmation, spinner, executable checks, and release operations.

moma confirm | spinner | command-check | version | update

Color themes

Load themes from ~/.config/momaui/moma.confg, list them, or select one for a command.

moma themes | moma --theme NAME msg "Ready"

Documentation commands

Open terminal, Markdown, web, or usage documentation.

moma preview [md|web] | help

`--color <color>`	Sets the heading color. Defaults to the primary color (cyan) when omitted.
`--margin-top <number>`	Blank lines printed above the heading. Defaults to 1.
`--margin-bottom <number>`	Blank lines printed below the heading. Defaults to 2.
`--margin-left <number>`	Spaces of left indent before every line. Defaults to 0.
`--no-color`	Strips ANSI color codes entirely, printing plain text.

`--success \| --error \| --warning \| --info`	Sets the border/icon color and the left marker to the matching semantic icon (✔, ✖, !, →).
`--primary <color>`	Sets the box border and title text color. Defaults to the primary color (cyan) when omitted.
`--accent <color>`	Sets the subtitle text color. Defaults to the accent color (yellow) when omitted.
`--icon <char>`	Sets the left marker. Defaults to ▪.
`--no-icon`	Drops the left marker in favor of a plain box edge (│).
`--border mirror \| line \| open`	Controls the right marker: mirror (default) repeats the left marker, line closes with a plain edge instead, open drops the right side entirely.
`--min-width <number>`	Minimum box width in characters. Defaults to 35.
`--width <number>`	Forces an exact box width, overriding automatic sizing. Unset by default.
`--max-width <number>`	Caps the box width when the content would be wider. Unset by default.

`--success \| --error \| --warning \| --info`	Sets the rule/text color and the left marker to the matching semantic icon (✔, ✖, !, →).
`--color <color>`	Sets the rule and text color. Defaults to the primary color (cyan) when omitted.
`--icon <char>`	Sets the left marker. Defaults to ▪.
`--no-icon`	Drops the left marker in favor of blank filler (there is no left box edge to fall back to here).
`--border mirror \| line \| open`	Controls the closing line: open (default) is a bare underline, line closes it with ┘, and mirror also closes it with ┘ and repeats the left marker at the end of the text line.
`--message <text>`	An optional extra line printed below the rule, after a blank line. Omitted by default.
`--min-width <number>`	Minimum width in characters. Defaults to 30.
`--width <number>`	Forces an exact width, overriding automatic sizing. Unset by default.
`--max-width <number>`	Caps the width when the content would be wider. Unset by default.

`--success \| --error \| --warning \| --info`	Sets the rule/text color and the left marker to the matching semantic icon (✔, ✖, !, →).
`--color <color>`	Sets the rule and text color. Defaults to the primary color (cyan) when omitted.
`--icon <char>`	Sets the left marker. Defaults to ▪.
`--no-icon`	Drops the left marker in favor of blank filler (there is no left box edge to fall back to here).
`--border mirror \| line \| open`	Controls the rule above the text: open leaves it without a ┐, line closes it with ┐, and mirror (default) also closes it with ┐ and repeats the left marker at the end of the text line.
`--min-width <number>`	Minimum width in characters. Defaults to 35.
`--width <number>`	Forces an exact width, overriding automatic sizing. Unset by default.
`--max-width <number>`	Caps the width when the content would be wider. Unset by default.

`--success \| --error \| --warning \| --info`	Semantic shortcuts that set both the heading color and its default icon (green ✔, red ✖, yellow !, cyan →).
`--icon <icon>`	Overrides the icon shown before the text.

Moma Terminal components

Colors

Visual

header

title

title-sub

sub-title

section

msg

msg-simple

list

box

resume

divider

label

Interactive

input

prompt

confirm

Selection

select

select-groups

multi-select

multi-select-groups

Decorative

rabbit

Utils

spinner

command-check

Self

update

version

preview

help

Command interface

`--success \| --error \| --warning \| --info`	Semantic shortcuts that set both the message color and its default icon (green ✔, red ✖, yellow !, cyan →).
`--color <value>`	Overrides the message color. Defaults to the primary color (cyan) when omitted.
`--icon <value>`	Overrides the icon shown around the text. No icon is shown by default unless a semantic flag sets one.

`--success \| --error \| --warning \| --info`	Sets just the marker color to the semantic color (green, red, yellow, cyan) - this component never shows an icon.
`--color <value>`	Overrides the marker color. Defaults to the primary color (cyan) when omitted.
`--marker <marker>`	Overrides the leading marker glyph. Defaults to "▪".

`--success \| --error \| --warning \| --info`	Sets the marker color for every item to the semantic color (green, red, yellow, cyan).
`--marker <marker>`	Overrides the marker glyph shown before each item. Defaults to "▪".
`--color <value>`	Overrides the marker color for every item. Defaults to the primary color (cyan) when omitted.

`--success \| --error \| --warning \| --info`	Sets both the border/text color and a default leading icon (green ✔, red ✖, yellow !, cyan →).
`--width <number>`	Forces an exact box width. Unset by default.
`--max-width <number>`	Caps the box width when the content would be wider. Unset by default.

`--title <text>`	Required block heading text. The component errors if this is never supplied.
`--item <term> <description>`	Repeatable. Adds one row with a bold term and a muted description, all terms aligned to the widest one in the block.
`--text <line>`	Repeatable. Adds one row of plain text with no term column.
`--success \| --error \| --warning \| --info`	Sets the border/title color to the semantic color and switches on the boxed header with the matching icon (✔, ✖, !, →).
`--color <color>`	Sets the block's border/title color. Defaults to the primary color (cyan) when omitted.
`--icon <char>`	Switches on the boxed header with this character as its left marker.
`--no-icon`	Switches on the boxed header with a plain box edge (│) instead of a marker.
`--border mirror \| line \| open`	Controls the closing edge: mirror and line (default: mirror) close with └, open leaves the block unclosed.
`--width <number>`	Forces an exact top-border width for the boxed header. Unset by default.
`--max-width <number>`	Caps the top-border width for the boxed header. Unset by default.
`--no-color`	Strips ANSI color codes entirely.

`--success \| --error \| --warning \| --info`	Sets the rule color and the marker to the matching semantic icon (✔, ✖, !, →).
`--color <color>`	Sets the rule color. Defaults to the primary color (cyan) when omitted.
`--icon <char>`	Sets the marker. Defaults to ▪.
`--no-icon`	Drops the marker in favor of blank filler (there is no left box edge to fall back to here).
`--border mirror \| line \| open`	open (default) prints just the rule; line and mirror both frame it with a bare ┌ above and └ below.
`--min-width <number>`	Minimum rule length in characters. Defaults to 35.
`--width <number>`	Forces an exact rule length, overriding automatic sizing. Unset by default.
`--max-width <number>`	Caps the rule length when it would be wider. Unset by default.
`--no-color`	Strips ANSI color codes entirely.

`--width <number>`	Forces an exact label width. Unset by default.
`--min-width <number>`	Minimum label width in characters. Defaults to 35.
`--max-width <number>`	Caps the label width when the content would be wider. Unset by default.
`--color <color>`	Sets the label border/text color. Defaults to the primary color (cyan) when omitted.
`--icon <symbol>`	An icon shown before the label text. None by default.
`--edge top \| bottom`	Which corner the rule uses: top (default) draws ┌/┐, bottom draws └/┘.
`--border line \| open`	line (default) closes the far end with the matching corner; open leaves it as a bare rule.
`--success \| --error \| --warning \| --info`	Sets both the color and a default icon together.

`--title <text>`	Label text shown above the field. Empty by default.
`--placeholder <text>`	Text displayed as the field's value only when no --default and no --value are set. Empty by default.
`--default <value>`	Fallback value used for display, and substituted in --read mode if the typed response is empty. Empty by default.
`--width <number>`	Forces an exact field width. Unset by default.
`--max-width <number>`	Caps the field width when the content would be wider. Unset by default.
`--secret`	Only meaningful with --read. Masks each typed character instead of echoing it.
`--mask <symbol>`	The character echoed for each keystroke when --secret is used. Defaults to "*".
`--read`	Switches from a static print into interactively reading one line of input from the terminal.
`--required`	Only meaningful with --read. Re-prompts until a non-empty value is produced.
`--trim`	Only meaningful with --read. Strips leading/trailing whitespace from the entered value.

`--success \| --error \| --warning \| --info`	Sets the color and the marker to the matching semantic icon (✔, ✖, !, →).
`--color <color>`	Sets the prompt color. Defaults to the warning color (yellow) when omitted.
`--icon <char>`	Sets the left marker. Defaults to ▪.
`--no-icon`	Drops the left marker in favor of blank filler.
`--border mirror \| line \| open`	Controls the underline: open (default) is a bare underline, line closes it with ┘, and mirror also closes it with ┘ and repeats the left marker at the end of the question line.
`--cursor <char>`	The symbol the answer is typed after. Defaults to "❯".
`--default <value>`	Shown as "[value]" after the question, and substituted if the typed response is empty. Empty by default.
`--secret`	Masks each typed character instead of echoing it.
`--mask <char>`	The character echoed for each keystroke when --secret is used. Defaults to "*".
`--required`	Re-prompts until a non-empty value is produced.
`--trim`	Strips leading/trailing whitespace from the entered value.
`--min-width <number>`	Minimum underline width in characters. Defaults to 30.
`--width <number>`	Forces an exact width, overriding automatic sizing. Unset by default.
`--max-width <number>`	Caps the width when the content would be wider. Unset by default.

`--default <yes\|no>`	Which answer starts highlighted, and is used automatically on an empty Enter. Defaults to "yes".
`--answer <yes\|no>`	Supplies the final answer directly and returns immediately without prompting - for scripts and tests. Interactive mode is used if omitted.

`--title <text>`	Heading shown above the menu. Defaults to "Select options".
`--choose <numbers>`	Comma-separated one-based indices to select immediately without interaction, for scripts and tests.
`--selected <numbers>`	Comma-separated one-based indices pre-checked before the menu is shown. None selected by default.
`--required`	Requires at least one option to be selected before confirming. Not required by default.
`--checkbox box\|brackets`	Checkbox style: box (default) draws ▣ and □, brackets draws [ x ] and [ ].

`--title <text>`	Heading shown above the menu. Defaults to "Select options".
`--group <name>`	Repeatable. Starts a named group, each with its own "All" toggle that selects/clears every option in that group at once.
`--option <value>`	Repeatable. Adds an option under the most recently declared --group.
`--selected <numbers>`	Comma-separated one-based global option indices pre-checked before the menu opens. None by default.
`--choose <numbers>`	Comma-separated one-based global option indices to select immediately without interaction, for scripts and tests.
`--required`	Requires at least one option selected before confirming. Not required by default.
`--checkbox box\|brackets`	Checkbox style: box (default) draws ▣, ▨ and □, brackets draws [ x ], [ - ] and [ ].

`--pid <number>`	The process ID to watch (can also be given as the first positional argument). Required.
`--message <text>`	Text shown next to the spinner, and reused as the completion message. Defaults to "Working" (can also be given as a second positional argument).
`--delay <seconds>`	Seconds between spinner-frame redraws. Defaults to 0.1.

`(no argument)`	Renders the full terminal component gallery to the screen.
`md`	Renders the Markdown-form documentation instead of the terminal gallery.
`web`	Opens the browser-based documentation instead of the terminal gallery.

`--title <text>`	Heading shown above the option list. Defaults to "Select an option".
`--choose <number>`	One-based index to select immediately without any interactive prompt - intended for scripts and automation. Interactive mode is used if omitted.
`--initial <number>`	One-based index highlighted when the menu first opens. Defaults to 1.
`--color <color>`	Highlight color for the active row. Defaults to the primary color (cyan) when omitted.

`--success \| --error \| --warning \| --info`	Sets both the message color and its default icon (green ✔, red ✖, yellow !, cyan →).
`--icon <icon>`	Overrides the icon shown before the message text. None by default.