Discussion: Should we re-add the CLI tool?

[aepfli]

Consider Re-adding CLI Tool for Testing and Development

Background

The CLI tool (flagd-eval) was removed in [commit hash] to simplify the project and focus on the WASM library. However, there may be value in reconsidering this decision.

Why the CLI Was Removed

1. Simplified Project - Clearer focus on WASM library purpose
2. Reduced Maintenance - No need to maintain CLI interface and cross-platform builds
3. Smaller Dependencies - Removed clap and colored dependencies
4. Faster CI - Eliminated cross-platform builds (Linux, macOS, Windows, ARM)
5. Testing Coverage - Integration and Gherkin tests provide comprehensive coverage

Use Cases for a CLI Tool

A CLI could provide value for:

1. Quick Manual Testing

• Test JSON Logic rules without writing code
• Rapid iteration during rule development
• Debugging complex targeting logic

2. Developer Experience

• Lower barrier to entry for trying the evaluator
• Interactive exploration of custom operators
• Educational tool for learning JSON Logic

3. CI/CD Integration

• Validate flag configurations in CI pipelines
• Run test suites as part of deployment checks
• Generate reports on rule complexity

4. Debugging

• Pretty-print evaluation results
• Show step-by-step rule evaluation
• Test edge cases quickly

Proposed CLI Features

If re-added, the CLI should be:

Minimal Scope

• Evaluate rules: flagd-eval eval --rule '{"==": [1, 1]}' --data '{}'
• Test suites: flagd-eval test suite.json
• List operators: flagd-eval operators

Implementation Approach

Option A: Separate Binary (Original)

• Keep as src/bin/flagd-eval.rs
• Feature-gate CLI dependencies
• Build with cargo build --bin flagd-eval

Option B: Workspace Member

flagd-evaluator/
├── lib/          # Core WASM library
└── cli/          # Separate CLI crate

• Complete separation from library
• Independent versioning
• No impact on WASM build

Option C: External Tool

• Separate repository
• Depends on flagd-evaluator as library
• Community maintained

Questions for Discussion

1. Is there demand? Have users requested a CLI tool?
2. Maintenance burden? Who would maintain it?
3. Distribution? Homebrew? cargo-binstall? GitHub releases?
4. Scope? What features are essential vs. nice-to-have?
5. Alternative? Could we provide example scripts instead?

Alternative Solutions

If we don't add a CLI, we could:

1. Example Programs - Add to examples/ directory

   // examples/evaluate_rule.rs
   fn main() {
       let rule = std::env::args().nth(1).expect("Usage: rule data");
       // ... evaluation logic
   }

2. Testing Scripts - Shell scripts for common operations

   #!/bin/bash
   # scripts/test-rule.sh
   cargo run --example evaluate_rule "$@"

3. Web UI - Browser-based testing tool (separate project)

4. Documentation - Comprehensive examples in README for each language

Decision Criteria

Consider re-adding if:

• ✅ Multiple users request it
• ✅ There's a maintainer willing to own it
• ✅ It provides clear value over alternatives
• ✅ Implementation can be kept simple

Don't re-add if:

• ❌ No user demand
• ❌ Examples and tests are sufficient
• ❌ Maintenance burden is high
• ❌ It distracts from core WASM focus

Related

• Original CLI implementation: [link to final commit before removal]
• Alternative testing approaches: See CLAUDE.md "Testing Philosophy" section