@ui-entropy/cli

Command-line interface for UI Entropy Scanner. Scan projects, track baselines, and enforce quality gates in CI/CD.

UI Entropy Scanner helps teams identify unused CSS, reduce bundle sizes, and prevent technical debt. This CLI tool provides smart project initialization, baseline tracking, and CI/CD integration.

Key Features:

• 🎯 Smart initialization - Auto-detects Next.js, React, Vue, Angular, Svelte frameworks
• 📊 Baseline tracking - Capture snapshots and compare CSS entropy over time
• 🚨 CI/CD enforcement - Fail builds when CSS quality degrades with --max-delta
• 📈 Entropy scoring - Weighted metrics combining waste and duplication analysis
• 🎨 Beautiful output - Color-coded deltas and formatted reports

For programmatic use, see @ui-entropy/scanner-core for the core analysis engine.

📦 Installation

# Install globally
npm install -g @ui-entropy/cli

# Or use with npx (no install required)
npx @ui-entropy/cli scan

🚀 Quick Start

# Initialize configuration (auto-detects your framework)
npx @ui-entropy/cli init

# Scan your project
npx @ui-entropy/cli scan

The init command automatically detects your framework (Next.js, React, Vue, Angular, Svelte, etc.) and generates a .ui-entropy.json config with sensible defaults.

Manual Usage

# Scan current directory
npx @ui-entropy/cli scan

# Scan specific project
npx @ui-entropy/cli scan /path/to/project

# Create baseline for CI/CD tracking
npx @ui-entropy/cli baseline --name "Production baseline"

# Compare against baseline
npx @ui-entropy/cli scan --compare --max-delta 5

# Get JSON output
npx @ui-entropy/cli scan --format json

# Set waste threshold for CI
npx @ui-entropy/cli scan --threshold 50  # Fails if waste > 50%

📊 Example Output

✔ Scan completed in 3601ms

📂 Project: /path/to/your/project
📊 Files: 4 CSS, 2307 source

🔍 UI Entropy Analysis Report
═══════════════════════════════════════════════════════

📊 Summary
─────────────────────────────────────────────────────
Total CSS Size:           8,200 bytes
Total Rules:              114
Files Scanned:            2307

🎯 Selectors
─────────────────────────────────────────────────────
Total Selectors:          61
Used Selectors:           41 (67%)
Unused Selectors:         20

Classes:                  58 total
  ├─ Used:                38
  └─ Unused:              20

IDs:                      3 total
  ├─ Used:                3
  └─ Unused:              0

💰 CSS Waste Analysis
─────────────────────────────────────────────────────
Waste Percentage:         32.8%
Estimated Wasted Bytes:   2,689 bytes

🚨 Top Unused Classes
─────────────────────────────────────────────────────
  1. .container-fluid
  2. .container-lg
  3. .btn-sm
  ...

🛠️ CLI Commands

init

Initialize UI Entropy with framework auto-detection.

ui-entropy init [options]

Detects your framework and creates .ui-entropy.json with sensible defaults.

Supported frameworks:

• Next.js, Create React App, Vite
• Vue, Angular, Svelte, Astro
• Static HTML projects

baseline

Create a baseline snapshot for CI/CD comparison.

ui-entropy baseline [options]

Options:

• --name <name> - Human-readable name for this baseline
• --description <desc> - Detailed description
• --force - Overwrite existing baseline without confirmation

Creates .ui-entropy-baseline.json with entropy score and Git metadata.

scan

Scan project for CSS waste.

ui-entropy scan [directory] [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --format <type> | Output format: text, json, summary | text | | --output <file> | Save results to file | (stdout) | | --compare | Compare against baseline | false | | --max-delta <number> | Max allowed entropy increase (requires --compare) | none | | --threshold <number> | Max waste % (exits 1 if exceeded) | none | | --css <pattern> | CSS file glob pattern | **/*.css | | --source <pattern> | Source file glob pattern | **/*.{html,js,jsx,ts,tsx,vue} | | --ignore <pattern> | Additional ignore patterns | none | | --config <file> | Config file path | .ui-entropy.json | | --no-color | Disable colored output | false |

⚙️ Configuration

Create .ui-entropy.json in your project root:

{
  "cssPattern": "**/*.css",
  "sourcePattern": "**/*.{html,jsx,tsx,vue}",
  "ignorePatterns": [
    "**/*.test.*",
    "storybook/**"
  ],
  "threshold": 50
}

️ Roadmap

Available Now:

• ✅ CLI tool for local development
• ✅ Smart project initialization with framework detection
• ✅ Baseline comparison and CI/CD enforcement
• ✅ Entropy scoring with pluggable analyzers

Coming Soon:

• 🔄 Team dashboards with historical analytics
• 🔄 Multi-project portfolio views
• 🔄 Advanced insights and reporting

📚 Documentation

• Main Documentation - Overview and getting started
• CI/CD Integration Guide - Baseline comparison setup
• Scanner Core API - Programmatic usage
• 🔄 GitHub Action for CI/CD
• 🔄 GitLab CI integration
• 🔄 Pre-commit hook support
• 🔄 Team dashboard with historical analytics
• 🔄 Multi-project portfolio views
• 🔄 Advanced insights and reporting
• 🔄 Slack/email alerts for waste spikes
• 🔄 Enterprise features and SSO

💡 Use Cases

• Before Deployment - Verify you're not shipping unnecessary CSS
• During Refactoring - Safely identify removable styles
• Code Reviews - Catch CSS bloat in PRs
• Performance Audits - Quick wins for bundle size reduction
• Technical Debt - Quantify and track stylesheet cleanup

🔗 Related Packages

• @ui-entropy/scanner-core - Programmatic API
• UI Entropy Dashboard (coming soon) - Team analytics platform

📚 Documentation

• Full Documentation
• API Reference
• Configuration Guide
• Best Practices

📝 License

Proprietary - See LICENSE file.
Free tier available. Pro/Team subscriptions for advanced features.

💬 Support

For CLI usage questions:

• 📖 Documentation
• 🐛 Report Issues

For commercial inquiries:

• Dashboard beta access
• Enterprise features
• Custom integrations
• Contact: [email protected]

Built with ❤️ and TypeScript for professional development teams.