RFD 0003: Composable CLI Commands Over Overloaded Flags¶

Summary¶

This RFD documents the decision to add four new focused CLI commands (search, info, config, diff) rather than extending existing commands with additional flags or building a single interactive TUI. The decision follows Unix philosophy: each command does one thing well.

Problem Statement¶

The Samuel CLI had 7 commands (init, update, add, remove, list, doctor, version). User feedback and analysis identified gaps:

1. Discoverability: No way to search for components by keyword
2. Preview: Can't see component details before installing
3. Configuration: Must manually edit samuel.yaml
4. Version comparison: Can't see what changed before updating

Users had to read documentation or guess component names. There was no safe way to preview changes before making them.

Background¶

Existing Commands¶

Missing Capabilities¶

• Search: Find components matching keywords
• Preview: See what a component contains before installing
• Config: Modify settings without editing YAML
• Diff: Compare versions before updating

Options Considered¶

Option A: Add 4 New Commands (Chosen)¶

Create dedicated commands for each new capability.

New commands:

• search - Fuzzy search across all components
• info - Show component details with preview
• config - Manage configuration via CLI
• diff - Compare versions before update

Pros:

• Each command has single responsibility
• Follows Unix philosophy (do one thing well)
• Easy to discover via --help
• Consistent with existing command patterns
• Scriptable and composable
• Easy to test individual commands

Cons:

• More commands to learn (11 instead of 7)
• More code to maintain
• Potentially overwhelming command list

Effort: Medium

Option B: Extend Existing Commands¶

Add new functionality as flags to existing commands.

• list --search <query> instead of search
• add --preview <name> instead of info
• list --config instead of config
• update --diff instead of diff

Pros:

• Fewer top-level commands
• Familiar pattern from some tools

Cons:

• Overloaded commands with too many flags
• Harder to discover features
• Complex --help output
• Mixing concerns in single commands

Effort: Low

Option C: Interactive TUI Mode¶

Single interactive command with menus and navigation.

samuel interactive  # Opens TUI with all features

Pros:

• Highly discoverable via browsing
• Rich visual interface
• Can combine all features

Cons:

• Doesn't work in scripts/CI
• Requires additional TUI library (tcell, bubbletea)
• Diverges from existing CLI patterns
• Higher maintenance burden
• Accessibility concerns

Effort: High

Proposal¶

Chosen: Option A - Four New Focused Commands

Rationale¶

1. Unix Philosophy: Each command does one thing well
2. Scriptability: All commands work in scripts and CI
3. Testability: Easy to test individual commands in isolation
4. Discoverability: samuel --help shows all capabilities
5. Consistency: Follows established CLI patterns (git, npm, docker)
6. Composability: Commands can be piped together

Command Specifications¶

Implementation Details¶

Search Command¶

samuel search react           # Finds react, react-native, etc.
samuel search --type language go  # Search only languages

• Uses Levenshtein distance for fuzzy matching (≤2 edits)
• Supports type filtering (language, framework, workflow)
• Shows relevance scores

Info Command¶

samuel info language go       # Show Go guide info
samuel info framework react --preview  # Show preview of content

• Displays file size, line count
• Shows related components
• Preview mode shows first N lines

Config Command¶

samuel config list            # Show all config
samuel config get project.name
samuel config set project.version 1.2.0

• Subcommands: list, get, set
• No manual YAML editing required
• Validates values before saving

Diff Command¶

samuel diff                   # Show what would change on update
samuel diff --installed       # Compare installed vs available
samuel diff v1.5.0 v1.6.0     # Compare specific versions

• Shows added, modified, removed components
• Helps users understand update impact
• Uses side-by-side diff format

Implementation Considerations¶

Files Added¶

internal/commands/
├── search.go
├── search_test.go
├── info.go
├── info_test.go
├── config_cmd.go
├── config_cmd_test.go
├── diff.go
├── diff_test.go
├── diff_display.go
└── diff_display_test.go

Testing Strategy¶

• Unit tests for helper functions (80%+ coverage target)
• Table-driven tests for edge cases
• Integration tests for command runners (future)
• 77+ test functions across 7 test files

Security Considerations¶

• config set validates input to prevent injection
• No network calls in search (local registry only)
• Diff doesn't expose sensitive information

Compatibility¶

• Breaking changes: None (additive only)
• Migration path: N/A (new features)
• Backwards compatibility: Existing commands unchanged

Consequences¶

Positive¶

• Users can discover components without reading docs
• Safe previews before installing/updating
• Configuration changes don't require manual YAML editing
• Version comparison reduces update anxiety
• Better CI/script support

Negative¶

• 4 more commands to maintain
• Increased test surface area
• Documentation needs updating
• Users have more commands to learn

Technical Debt Created¶

• Integration tests not yet implemented for command runners
• README documentation needs updating

References¶

• PRD: .claude/tasks/0004-prd-cli-command-enhancements.md
• Decision documented: .claude/memory/2026-01-14-cli-command-enhancements.md
• Patterns: .claude/patterns.md (Fuzzy Search Pattern, Testing Patterns)
• Unix Philosophy: wikipedia.org/wiki/Unix_philosophy