Skip to main content

rungs — interactive menus for fuzzy Linux procedures

PyPI version Python versions License: MIT PyPI downloads CI

rungs turns a plain .ini file into a friendly, keyboard-driven menu for running shell commands — one rung at a time up the ladder of a procedure.

It is built for fuzzy procedures on Linux, where the exact steps depend on what you encounter along the way:

  • skip steps whose vague preconditions are already met, and
  • repeat steps that failed — because retrying them makes sense.

Instead of scrolling back through your shell history (or keeping a notes file of cryptic one-liners), you get a menu where you highlight the next step, hit Enter, and watch it run. Which step you run next is your call.

Typical configs are system updates and Docker housekeeping — the chores with "too many commands to remember". rungs also makes a great executable runbook — see Executable runbooks (stepped specs).

eos-update-menu


Why rungs?

Fuzzy, not fixed A procedure is a menu, not a script. You decide what runs next based on what you observe.
Tiny & self-contained Pure Python standard library — no dependencies. One .ini file holds every menu.
Nothing to remember Commands live in a readable config; the menu shows descriptions for the messy ones.
Recoverable Every valid config is auto-backed-up to rungs.ini.bak, so a bad edit is easy to undo.
Composable Menus can launch other menus, so you can build multi-level procedures.

Executable runbooks (stepped specs)

rungs shines when a procedure is too fuzzy for a script but too important to leave in a wiki page: a "kick the tires" check of a freshly installed package, a host-specific teardown, or a manual integration test. Call it the layer between make test and a wiki page.

Unit tests prove your logic against mocks; they never see the real host. A stepped spec proves the product actually wired itself into the box — $PATH, the pipx launcher, the systemd unit, /dev/zram0, sudo. A missing /usr/local/bin/... (reported as command not found), a --unsetup that deletes itself, or a stray /tmp file are invisible to mocks; a stepped spec catches them by looking at the machine.

Why rungs is a good vehicle for it:

  • Human-in-the-loop is the feature. Unloading swap, removing a service, and reaching for sudo are exactly where automation is unsafe. Just pick another entry to skip a step, or run it again to repeat one — the right model for a fuzzy procedure.
  • Noisy evidence, plus a machine verdict. You read the EXPECT: lines while CI greps the same run for a marker. One artifact serves both the human and the machine — a runbook you can also run in CI.
  • Zero deployment. An ad-hoc .ini file, +ENV for shared tokens, and auto-keys mean the spec lives versioned in your repo, not in ~/.config.

Each check prints its raw evidence, states what to EXPECT:, then a one-line verdict pulled from $OK_MSG / $FAIL_MSG:

[__GLOBAL__]
+ENV: OK_MSG=✓✓✓✓✓✓✓✓✓✓ OK
      FAIL_MSG=✘✘✘✘✘✘✘✘✘✘ FAIL

[smoke]
01: :: *Install the working tree          # state-changing; '*' butts the text
   pipx install --force .
02: ::  - CHK: launcher is on PATH. EXPECT: a resolved path
   echo '$ command -v mytool'
   command -v mytool
   command -v mytool >/dev/null 2>&1 \
     && { echo; echo "$OK_MSG"; } \
     || { echo; echo "$FAIL_MSG"; exit 1; }
x: exit

Run it (needs a TTY, and a human for the risky steps):

rungs samples/IntegrationSpec.ini

Capture the run and let CI read the verdict:

rungs samples/IntegrationSpec.ini | tee run.log
grep -q '✓✓✓' run.log && echo PASS || echo FAIL

The TTY-and-human requirement is a feature: it is exactly the layer automation should not cover. Use it alongside your mocked unit tests, not as a replacement for them. See samples/IntegrationSpec.ini for a runnable example that "kicks the tires" of a rungs install.

Requirements

  • Python 3.11+
  • A POSIX-ish terminal (Linux); reads single keypresses via termios

Installation

rungs is a console app, so pipx is the recommended way to install it in an isolated environment:

python3 -m pip install --user pipx        # if pipx isn't installed
python3 -m pipx ensurepath                # if needed (restart your terminal)
pipx upgrade rungs || pipx install rungs  # install / upgrade

Prefer a plain pip install? That works too:

python3 -m pip install --user --upgrade rungs

Quick start

rungs                 # show a menu of all your menus, then pick one
rungs eos-update      # run a specific menu directly
rungs my-procedure    # run an .ini file directly (any filename)
rungs --edit          # edit your configuration file
rungs --dry-run       # show the commands without running them

Once a menu is up:

  • type the key shown before the : (or move with ↑/↓),
  • press Enter to run the highlighted command,
  • after it finishes, the next entry is pre-selected — just press Enter to continue, or pick any other entry to skip/repeat.

Note: a menu that does not fit is folded, not scrolled out of reach: hidden entries collapse into a single row at the top or bottom (e.g. <<<<<<< a..e), and the fold re-opens as the cursor approaches it. The folds show the keys of the hidden range, so you can also jump straight to one by typing its key. If the terminal is shorter than six rows, rungs shows a resize hint and waits; it re-flows automatically when the terminal grows.

Ctrl-C behaves politely

Ctrl+C will not knock rungs over and wreck the display:

  • At the menu, a single Ctrl-C is swallowed so the display is not torn down mid-draw; it shows a hint asking you to press Ctrl-C again to exit. A second Ctrl-C in a row (with no other key in between) is the escape hatch.
  • While a command runs, it interrupts that command only; rungs returns to the menu with the step pre-selected so you can read the result (a command stopped by Ctrl-C is reported as status 130) and retry or pick another step.

Configuration: ~/.config/rungs/rungs.ini

The first time you run rungs it creates a config for you. A menu is just an .ini section; each entry is key: command.

[eos-update]
a: my-snaps                                 # replace snaps of root, home, etc.
b: sudo reflector -l20 -cus,ca --sort rate --save /etc/pacman.d/mirrorlist
c: eos-rankmirrors                          # update EndeavourOS mirrors
d: eos-update --yay                         # EndeavourOS update script
e: sudo paccache -rk1; sudo paccache -ruk0  # cleanup cache
f: sudo pacman -Rns $(pacman -Qdtq)         # cleanup orphans
g: flatpak update
h: flatpak uninstall --unused; flatpak repair
i: sudo journalctl --vacuum-time=2weeks
j: sudo reboot now
x: exit

Notes:

  • This config mirrors the menu you see, so the menu is the documentation.

  • For long commands, put a description on the first line and the command on the indented lines that follow — the menu shows the description and bash receives the rest, literally:

    b: prompt-b          # shown in the menu
       command-b         # sent to bash literally
    
  • Keys must be unique within a menu. A one-character key is used literally, so make it a mnemonic when you can (a: add, d: delete).

  • A longer key is a placeholder that only needs to be unique in the file; rungs assigns it the next free display character (a, b, c, ...) in file order, leaving x free for the conventional exit entry. This lets you insert a step without re-lettering its neighbors:

    [maint]
    a: add                          # literal mnemonic
    00: git fetch --all             # auto key -> b
    037: prune merged branches      # auto key -> c
    x: exit
    
  • exit (or quit) closes the menu. By convention it is placed on x (a mnemonic that leaves room for many steps before it), but the key is not special: a menu without it is left with Ctrl-C twice.

Environment variables (+ENV)

A section can set environment variables that every command in that section sees, using a +ENV entry whose value is one NAME=VALUE per line:

[docker-maint]
+ENV: DOCKER_HOST=tcp://127.0.0.1:2375
      REGISTRY=registry.local
a: docker system df
x: exit

Notes:

  • The block applies to the whole section and is removed when you leave it — your shell is unaffected, and sub-menus launched from the section inherit it.
  • Values are de-quoted and $VAR references are expanded when the section starts, so PATH=$PATH:/opt/bin works.
  • The directive's key is literally +ENV — a reserved, +-prefixed name that is never a menu entry. Only one +ENV block per section is allowed — list every variable on its own indented line; two +ENV entries make the file invalid.
  • Removing variables is not supported.
  • Write +ENV first in the section by convention; it reads more clearly, although its position does not change what it does.

To share variables across all sections, use the reserved, hidden [__GLOBAL__] section, which accepts only +ENV and +PRE:

[__GLOBAL__]
+ENV: REGISTRY=registry.local
      PKG=dnf

[__GLOBAL__] never appears in the menu list, is applied once at start-up, and is inherited by every section and sub-menu. A section's own +ENV overrides a global of the same name while that section runs, and the global is restored afterwards.

Shared preambles (+PRE)

A section can prepend a chunk of shell text to every command it runs, using a +PRE entry. This is a preamble, not an exported shell function: each command runs in a fresh /bin/sh, so define whatever you need — variables, helper functions — as plain shell text, and it is re-stated before each command:

[test-suite]
+PRE: fail=0
      OK_MSG='all good'
      report() { echo "$1: $OK_MSG"; }
      verdict() { if [ "$fail" -eq 0 ]; then echo PASS; else echo FAIL; fi; }
a: run-tests && report tests
   verdict
x: exit

Notes:

  • The block applies to the whole section and is inherited by sub-menus launched from it. A section's own +PRE comes after any global / inherited preamble, so it can redefine a helper it inherited.
  • +PRE is not de-quoted or $VAR-expanded (unlike +ENV): the text is handed to the shell verbatim. That is what lets a helper's $fail stay a reference until the command actually runs — the reason a distinct directive is needed rather than stuffing the snippet into +ENV.
  • The preamble is echoed once at the top of the section (==> [preamble]); each step then echoes only its own command, so the shared snippet is not reprinted before every run.
  • Only one +PRE block per section is allowed — like +ENV, list every line indented beneath the directive.

+PRE may also live in [__GLOBAL__], so helpers used by every menu are defined in one place:

[__GLOBAL__]
+PRE: log() { printf '%s\n' "$*" >&2; }
+ENV: REGISTRY=registry.local

Command line

usage: rungs [-h] [-e] [-n] [menus ...]

positional arguments:
  menus          zero or more menu names or .ini file paths

options:
  -h, --help     show this help message and exit
  -e, --edit     edit config (i.e., runs edit-rungs-config)
  -n, --dry-run  show commands w/o running them
  --version      show program's version number and exit

Menu names can be matched:

  • exactly (eos-update, and any "special" name),
  • case-insensitively exactly (if unique and ordinary), e.g. EOS-UPDATE,
  • or by a case-insensitive substring at a word boundary (if unique and ordinary) — for menus ['edit-rungs-config', 'example', 'eos-update']:
    • edit, ex, EOS- and EOS-UPDATE all resolve,
    • but date and e do not.

Running an ad-hoc file

Each positional argument is resolved in order:

  1. if it contains no /, it is tried as a menu name first (as above);
  2. otherwise — the name wasn't found, or it contains a / — it is treated as a path to an .ini file. The filename may be anything (my-procedure, notes.txt, ...); only the contents must be .ini format;
  3. if it is neither a known menu nor a readable menu file, rungs treats it as misuse and exits with a usage error.
rungs samples/DockerMaintenance.ini   # a file (name ends in .ini)
rungs my-procedure                    # a file by any other name
rungs ./notes                         # a path containing a slash

An ad-hoc file behaves like a slice of your config: a single ordinary menu runs directly, several are offered as a list, and a >sub menu defined in the file is still reachable via rungs '>sub' (the file is handed to the child process automatically).

Ordinary vs. special menus

A menu name beginning with a word character ([_A-Za-z0-9]) is ordinary and can be fuzzy-matched. A name beginning with anything else is special: it is hidden from the "all menus" list and only runs when you give its exact name. Suggested conventions:

  • >name — a sub-menu that shouldn't be called on its own,
  • !name — a deprecated menu you're not ready to delete yet.

The edit menu & recovering a broken config

rungs --edit opens the edit-rungs-config menu, whose default action launches ${EDITOR:-vi}. Do not remove that menu — it powers --edit and recovery.

If your .ini ever becomes corrupt, rungs prints the error and drops you into edit-rungs-config. After every successful read, your config is copied to ~/.config/rungs/rungs.ini.bak; restore it manually if you make a terrible edit.

Examples

The samples/ directory has ready-to-adapt menus:

These are not tested against the latest distro releases — review them before running.

Recipes

  • System update: mirrors → package manager update → flatpak → cache/orphan cleanup → reboot.
  • Docker housekeeping: docker system df → prune images/containers/volumes → docker system prune → review leftover networks.
  • Onboarding a machine: snapshots → config sync → dotfiles → reboot.

License

MIT — see LICENSE.

Mnemonic: step through the rungs of your laddered procedure.

Metadata

Release files for rungs 1.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rungs 1.4.1
File Size Uploaded Provenance Actions
rungs-1.4.1.tar.gz 27.5 kB Without provenance Details for rungs-1.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rungs 1.4.1
File Interpreter ABI Platform Actions
rungs-1.4.1-py3-none-any.whl Python 3 none any Details for rungs-1.4.1-py3-none-any.whl

Total release size: 50.5 kB

Release files / rungs-1.4.1.tar.gz

Download URL rungs-1.4.1.tar.gz
Size 27.5 kB
Tags Source
SHA-256 checksum
How to use checksums
819cb84fc28ddf7d7135a049bcd8c213036f69f20ec356e43a0e6c95feb20f97
BLAKE2b-256 checksum
How to use checksums
3aa9a5959ccfa3b317340bbf937024180f8c0a572228dc6943d36a7cb630363c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Release files / rungs-1.4.1-py3-none-any.whl

Download URL rungs-1.4.1-py3-none-any.whl
Size 23.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
73af1f7fe3b85cc830665cdfd0f0c5fb43e4c048854e6f2f51d9b6ba0cefead8
BLAKE2b-256 checksum
How to use checksums
b0338ef6072bc67faddc0e58b4b18284632c2476391558f781e1c530dccc3a92
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Security for rungs 1.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page