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

Shortcut mode

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

g>bs   →  git › switch-and-pull
g>bc   →  git › create-branch-push
d>cu   →  docker › up

Built-in macros

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

g — Git

d — Docker

n — Node

m — Mango

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):

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