🚀 Hybrid CLI+TUI Pattern: Cobra + Phoenix Integration

[kolkov]

Tags: #tutorial #cobra #patterns #best-practices

---

🎯 The Problem

Modern CLI tools face a dilemma:

• Scripts need flags (--name "John") for automation
• Humans want interactive UIs with guided workflows

Most tools force you to choose one approach. What if you could have both?

💡 The Solution: Hybrid CLI+TUI Pattern

One tool, two modes:

# CLI Mode (flags) → For scripts, CI/CD, automation
./mytool --name "John" --email "john@example.com" --message "Hello!"

# TUI Mode (interactive) → For humans, onboarding, exploration
./mytool  # No flags? Launch beautiful TUI!

Same tool, different UX depending on usage!

🏗️ How It Works

1. Use Cobra for CLI Structure

Cobra is the industry-standard CLI framework (used by kubectl, gh, docker, hugo):

var rootCmd = &cobra.Command{
    Use:   "mytool",
    Short: "A demo tool showing Cobra + Phoenix integration",
    Run: func(cmd *cobra.Command, args []string) {
        // If any flags provided → CLI mode
        if cmd.Flags().NFlag() > 0 {
            runCLIMode()
            return
        }

        // No flags → TUI mode
        runTUIMode()
    },
}

func init() {
    rootCmd.Flags().StringVarP(&name, "name", "n", "", "Your name")
    rootCmd.Flags().StringVarP(&email, "email", "e", "", "Your email")
    rootCmd.Flags().StringVarP(&message, "message", "m", "", "Your message")
}

2. Use Phoenix for TUI Mode

Phoenix provides production-ready TUI components:

func runTUIMode() {
    // Create beautiful form with Phoenix components
    nameInput := components.NewTextInput(
        components.WithPlaceholder("Enter your name..."),
        components.WithStyle(style.New().
            Foreground(style.Color("#00FF00"))),
    )

    emailInput := components.NewTextInput(
        components.WithPlaceholder("your.email@example.com"),
        components.WithStyle(style.New().
            Foreground(style.Color("#00AAFF"))),
    )

    // Create model and run
    m := newFormModel(nameInput, emailInput)
    p := tea.NewProgram(m, tea.WithAltScreen())
    p.Run()
}

📦 Full Working Example

I've created a complete example showing this pattern:

Location: examples/cobra-cli/

Features

✅ CLI Mode - Scriptable, automation-friendly

./cobra-cli --name "John" --email "john@example.com" --message "Hello Phoenix!"

✅ TUI Mode - Beautiful, guided, interactive

./cobra-cli  # No flags → launches TUI

✅ Tab Navigation - Move between fields with Tab/Shift+Tab
✅ Real-time Validation - Immediate feedback on input
✅ Beautiful Styling - Colors, borders, emojis 🎨
✅ Cross-platform - Works on Linux, macOS, Windows

Try It Yourself

# Clone Phoenix repository
git clone https://github.com/phoenix-tui/phoenix
cd phoenix/examples/cobra-cli

# Run CLI mode
go run main.go --name "John" --email "john@example.com" --message "Testing!"

# Run TUI mode
go run main.go  # No flags!

🎨 Why Phoenix Over Charm?

This pattern works with Charm too (Huh + Lipgloss), but Phoenix offers critical advantages:

Feature	Charm (Huh/Lipgloss)	Phoenix
Unicode/Emoji	❌ Broken (#562)	✅ Perfect
Performance	~60 FPS	29,000 FPS
Test Coverage	Unknown	91.8%
Architecture	Monolithic	DDD layers

The Unicode Problem

// Charm/Lipgloss - BROKEN (8+ months):
prompt := "Name 👋: "  // Emoji width counted wrong
// Result: layout breaks, text overflows, alignment fails

// Phoenix - WORKS:
prompt := "Name 👋: "  // Perfect grapheme cluster detection
// Result: perfect layout, correct alignment ✓

Real impact: If your users have names with emojis, CJK characters, or combining marks → Charm breaks, Phoenix works.

🌍 Real-World Use Cases

This pattern is perfect for:

1. DevOps Tools

# CI/CD pipeline (CLI mode)
./deploy --env production --service api --version 1.2.3

# Developer exploration (TUI mode)
./deploy  # Interactive: select env, service, version from lists

2. Database Tools

# Automated backups (CLI mode)
./dbutil backup --database mydb --output /backups/

# Interactive admin (TUI mode)
./dbutil  # TUI: browse tables, run queries, view stats

3. Configuration Tools

# Ansible/Terraform (CLI mode)
./config apply --file config.yaml --dry-run

# First-time setup (TUI mode)
./config  # Guided wizard with validation

4. Monitoring Tools

# Alerting scripts (CLI mode)
./monitor check --service api --threshold 90

# Live dashboard (TUI mode)
./monitor  # Real-time graphs, logs, metrics

📚 Documentation

Full example with detailed README:

• Code: examples/cobra-cli/main.go (300+ lines with comments)
• README: examples/cobra-cli/README.md (comprehensive guide)
• Topics covered:
  • Architecture patterns
  • Best practices
  • Validation strategies
  • Production deployment
  • Troubleshooting

🔧 Extending the Pattern

Add More Components (Phoenix v0.2.0+)

// Select dropdown (coming soon!)
selectInput := components.NewSelect(
    components.WithOptions([]string{"Option 1", "Option 2", "Option 3"}),
)

// Multi-select (coming soon!)
multiSelect := components.NewMultiSelect(
    components.WithOptions([]string{"Feature A", "Feature B", "Feature C"}),
)

// Confirm dialog (coming soon!)
confirm := components.NewConfirm(
    components.WithMessage("Are you sure you want to proceed?"),
)

Add Subcommands

var createCmd = &cobra.Command{
    Use:   "create",
    Short: "Create a new resource",
    Run: func(cmd *cobra.Command, args []string) {
        if cmd.Flags().NFlag() > 0 {
            runCLICreate()  // CLI: create --name "foo"
        } else {
            runTUICreate()  // TUI: interactive creation wizard
        }
    },
}

rootCmd.AddCommand(createCmd)

🎓 Lessons Learned

1. Always Validate in Both Modes

// CLI mode
if name == "" {
    fmt.Fprintln(os.Stderr, "Error: --name is required")
    os.Exit(1)
}

// TUI mode
func (m formModel) isFormValid() bool {
    return m.nameInput.Value() != ""
}

2. Auto-detect CI Environments

// Force CLI mode in CI/CD
if os.Getenv("CI") != "" || !term.IsTerminal(int(os.Stdin.Fd())) {
    runCLIMode()
}

3. Consistent Output Format

// Both modes should produce same output
// Good for piping: ./tool | jq .name

🚀 What's Next?

Phoenix v0.2.0 will add more form components inspired by Huh:

• Select - Dropdown selection
• MultiSelect - Multiple choice
• Confirm - Yes/No dialogs
• Form - Grouped inputs with validation

But with Phoenix advantages:

• ✅ Correct Unicode support
• ✅ 10x faster performance
• ✅ DDD architecture (easier to customize)
• ✅ 90%+ test coverage

💬 Discussion

Questions:

• Do you use the hybrid CLI+TUI pattern in your projects?
• What other components would you like to see in Phoenix?
• Have you hit Unicode issues with Charm ecosystem?

Show us your projects! If you build something with Phoenix + Cobra, share it here! 🙌

---

📎 Links

• Phoenix GitHub: https://github.com/phoenix-tui/phoenix
• Example Code: examples/cobra-cli/ in Phoenix repo
• Getting Started: Tutorial
• Migration Guide: From Charm
• Cobra: https://github.com/spf13/cobra

---

Built with 🔥 Phoenix TUI Framework v0.1.0-beta.6
Inspired by: Habr article on Go TUI utilities

Let's build the future of Go CLI tools together! 🚀