Ruby CLI Development

Build Ruby CLI tools using Thor for commands and Zeitwerk for autoloading.

Quick Navigation

• Starting a new CLI gem from scratch? See references/bootstrap.md

• Adding commands or subcommands? See references/patterns.md

• Thor syntax reference? See references/patterns.md

• Rich terminal UI with Gum? See references/gum.md

Core Principles

• Use compact class declarations: class GemName::Cli::Main < GemName::Cli::Base

• Use extend self instead of module_function for utility modules

• Keep the Base class lean - add helpers as patterns emerge

Output Styling

For basic output, use Thor's built-in say "message", :color .

For rich terminal UI (headers, tables, spinners, confirmations), use the Gum gem:

ui.header("Section Title") # branded header with border ui.success("Done!") # green checkmark ui.error("Failed") # red X ui.table(rows, columns: [...]) # formatted table ui.spin("Working...") { ... } # spinner during work

See references/gum.md for setup and full API.

Tips & Gotchas

• Add # rubocop:disable Rails/Output to UI modules (stdout is intentional in CLIs)

• Gum requires brew install gum on the host machine