playbooks

home / skills / steveclarke / dotfiles / ruby-cli

ruby-cli skill

/ai/skills/ruby-cli

This skill helps you build and maintain Ruby CLI tools with Thor and Zeitwerk, guiding patterns, UI, and auto-loading best practices.

npx playbooks add skill steveclarke/dotfiles --skill ruby-cli

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.6 KB
---
name: ruby-cli
description: Build and maintain Ruby CLI tools using Thor and Zeitwerk. Use when creating new Ruby CLI gems, adding commands, editing CLI code, refactoring, or enhancing existing CLI tools. Triggers on "Ruby CLI", "Thor CLI", "command-line tool in Ruby", or when working on files in a Thor/Zeitwerk CLI codebase.
---

# 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](references/bootstrap.md)
- **Adding commands or subcommands?** See [references/patterns.md](references/patterns.md)
- **Thor syntax reference?** See [references/patterns.md](references/patterns.md)
- **Rich terminal UI with Gum?** See [references/gum.md](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:

```ruby
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](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

Overview

This skill helps you build and maintain Ruby command-line tools using Thor for command structure and Zeitwerk for autoloading. It focuses on creating new CLI gems, adding or refactoring commands, and integrating rich terminal UI patterns. The guidance emphasizes minimal, testable base classes and consistent output handling.

How this skill works

The skill inspects Thor-based command classes, Zeitwerk autoload layouts, and UI helper modules to suggest changes, add commands, or refactor code into patterns. It recommends compact class declarations, utility module conventions, and when to introduce helpers in a lean Base class. It also offers output styling options and integration notes for Gum when richer terminal UI is needed.

When to use it

  • Starting a new Ruby CLI gem or scaffolding a CLI structure.
  • Adding commands, subcommands, or flags to an existing Thor CLI.
  • Refactoring CLI command classes or reorganizing autoloaded code with Zeitwerk.
  • Improving or standardizing terminal output and UX across machines.
  • Integrating advanced UI elements (spinners, tables, confirmations) using Gum.

Best practices

  • Declare command classes compactly, e.g., class GemName::Cli::Main < GemName::Cli::Base.
  • Keep the Base class small; add helper methods only as common patterns emerge.
  • Use extend self for utility modules to provide module-level methods cleanly.
  • Route simple output through Thor's say for basic messages and use a UI wrapper for richer elements.
  • Add rubocop:disable comments for intentional stdout use in UI modules to avoid lint noise.

Example use cases

  • Scaffold a new CLI gem with a Main command and Zeitwerk-friendly folder layout.
  • Add a 'sync' subcommand that performs background work and shows a Gum spinner.
  • Refactor duplicated flag parsing into helper methods on the Base class.
  • Replace ad-hoc puts calls with ui.success/ui.error for consistent branding and color.
  • Document and install Gum on developer machines to enable rich terminal features.

FAQ

Do I need Gum to build a Thor CLI?

No. Gum is optional for richer UI elements. Thor's say covers basic colored output and is sufficient for many CLIs.

How should I structure files for Zeitwerk?

Follow Zeitwerk naming and directory conventions: nested modules map to nested directories and file names match class/module names for predictable autoloading.

When should helpers move from Base to a module?

Move helpers to modules when they are reusable across multiple command classes or when they grow beyond a few lines to keep Base lean.