oosh – Annotation-driven CLI framework for Bash

Hi HN, I built oosh because I was tired of rewriting the same flag parsing, help text, and completion logic every time I needed a bash CLI at work.

The initial idea came from 9 years ago: https://gist.github.com/bruno-de-queiroz/a1c9e5b24b6118e45f4..., and it's pretty simple: annotate your functions and oosh gives you flag parsing, help generation, tab completion, and type validation for free. A scaffolder generates a full CLI project in seconds.

```bash #@flag -e|--env ENV "staging" enum(dev,staging,prod) ~ target environment

#@public ~ deploy the app function deploy() { echo "Deploying to $ENV..." } ```

That's it. No subshells, no external dependencies, no compilation step. Just bash 3.2+ (works on stock macOS).

A few things that might interest this crowd:

- *530* lines for the whole framework `oo.sh` - *~45 annotations replace ~130 lines* of manual case statements, getopts, help text, and completion scripts - *6-17ms overhead* on macOS, 6-9ms on Linux — measured with a built-in profiler - *Tab completion* works out of the box for bash and zsh, including dynamic enums - *Linter* catches annotation errors, naming issues, and flag collisions - Built to be *agent-friendly* — LLMs can read the annotations and scaffold modules without understanding bash arg parsing

The 30s demo video in the README shows the full flow: install, scaffold, run commands, add a module, and autocomplete.

Happy to answer questions about the design decisions or bash 3.2 compatibility war stories.