mango-tui 0.2.4

Keyboard-driven TUI for running multi-step shell command sequences defined in YAML

🥭 mango

A keyboard-driven TUI for running your shell command sequences — no more copy-pasting the same commands.

---

---

Install

pip install mango-tui

Requires Python 3.10+.

Run

mango

That's it. On first run mango creates its config at ~/.config/mango/ and opens the TUI.

---

How it works

mango lets you define macros — named sequences of shell commands — grouped by category. You pick one from the TUI and it runs, streaming output to the bottom panel in real time.

Macros that need input (a branch name, a service, a version tag) show a prompt dialog before running.

---

Keyboard reference

Key	Action
↑ / ↓	Move through the list
← / →	Switch between category and macro panels
Enter	Run the selected macro
Tab / Shift+Tab	Cycle focus (categories → macros → shortcut bar)
q	Quit

Shortcut mode

Type <category>><macro> at any time to jump straight to a macro without using the menus:

g>su   →  git › switch-and-pull
g>cb   →  git › create-branch-push
d>up   →  docker › up

---

Built-in macros

mango ships with a set of common macros ready to use:

g — Git

Shortcut	Description
g>cb	Create a new branch and push it to origin
g>su	Switch to a branch, fetch and pull
g>db	Delete branch locally and on remote, then prune
g>nt	Create a new tag and push it
g>st	Show git status
g>lo	Show the last 10 commits

d — Docker

Shortcut	Description
d>up	docker compose up -d
d>dn	docker compose down
d>lg	Follow logs for a service

m — Mango

Shortcut	Description
m>up	Upgrade mango to the latest version

---

Adding your own macros

Create ~/.config/mango/config.local.yaml. Your macros are merged with the built-in defaults and survive package upgrades.

categories:
  git:
    shortcut: "g"          # must match an existing category exactly to add macros into it
    macros:
      cleanup:
        shortcut: "cl"
        description: "Delete merged branches"
        steps:
          - git branch --merged | grep -v main | xargs git branch -d

  tools:                   # a new category — key and shortcut must not exist in the defaults
    shortcut: "t"
    macros:
      hello:
        shortcut: "hi"
        description: "Say hello"
        steps:
          - echo "hello world"

Macros with parameters

Use params to collect input before the steps run. Reference each param in steps as {name}:

categories:
  tools:
    shortcut: "t"
    macros:
      deploy:
        shortcut: "dp"
        description: "Deploy to an environment"
        params:
          - name: env
            prompt: "Environment (staging/prod)"
        steps:
          - ./deploy.sh {env}
          - echo "Deployed to {env}"

---

Config files

mango manages three files under ~/.config/mango/ (respects $XDG_CONFIG_HOME):

File	What it is
config.default.yaml	Built-in macros — overwritten on each update
config.local.yaml	Your macros — edit this one
commands.yaml	Merged result read by the app — do not edit

Merge rules

• To add macros into an existing category: use the same category key and shortcut as the default.
• To add a new category: both the key and shortcut must not conflict with any default.
• Within a shared category, each local macro key and shortcut must be unique.

Conflicts are skipped and reported before the TUI opens:

[mango] config conflict: macro 'git>status' — key already defined in default (skipped)

---

YAML schema reference

categories:
  <category-key>:
    shortcut: "g"            # unique globally; one or more chars
    macros:
      <macro-key>:
        shortcut: "su"       # unique within its category
        description: "..."
        params:              # optional
          - name: branch
            prompt: "Branch name"
        steps:               # run sequentially; first non-zero exit aborts
          - git checkout {branch}
          - git fetch
          - git pull