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)
• The gum gem bundles the gum binary for common platforms; GUM_INSTALL_DIR points it at a system install elsewhere