cli/README.md

UX Analyst CLI

A command-line interface for AI-powered UX analysis of websites.

Installation

Option 1: NPM Package (Recommended)

# Install globally
npm install -g ux-analyst-cli

# Or run directly with npx
npx ux-analyst-cli https://example.com

Option 2: Local Development

# Clone and install dependencies
cd ux-analyst-ai/cli
npm install

# Link for global use
npm link

# Or run directly
node bin/ux-analyze.js https://example.com

Quick Start

# Basic analysis
ux-analyze https://example.com

# Interactive mode
ux-analyze interactive

# Quick analysis with code generation
ux-analyze https://example.com --quick --code

# Full analysis with custom output
ux-analyze https://example.com --format html --output ./my-analysis

Commands

ux-analyze <url> [options]

Analyze a website and generate UX recommendations.

Arguments:

• <url> - Website URL to analyze

Options:

• -o, --output <dir> - Output directory (default: ./ux-analysis)
• -f, --format <format> - Output format: json, html, markdown (default: json)
• -v, --viewports <list> - Comma-separated viewports (default: desktop,tablet,mobile)
• --quick - Run quick analysis (faster, less detailed)
• --code - Generate implementation code
• --accessibility - Include accessibility analysis
• --config <file> - Configuration file path
• --api-key <key> - Gemini API key

Examples:

# Comprehensive analysis
ux-analyze https://mysite.com --format html --code --accessibility

# Quick mobile-only analysis
ux-analyze https://mysite.com --quick --viewports mobile

# Custom output location
ux-analyze https://mysite.com --output /path/to/results

ux-analyze interactive

Interactive mode with guided prompts.

ux-analyze interactive
# or
ux-analyze i

ux-analyze config

Configure CLI settings (API key, defaults).

ux-analyze config

Configuration

Environment Variables

# Required: Gemini API key
export GEMINI_API_KEY="your-api-key-here"

Configuration File

Create a ux-config.json file:

{
  "ai": {
    "geminiApiKey": "your-api-key"
  },
  "defaults": {
    "viewports": ["desktop", "tablet", "mobile"],
    "outputFormat": "html",
    "includeCode": true,
    "includeAccessibility": true
  }
}

Use with: ux-analyze https://example.com --config ux-config.json

Output Formats

JSON (Machine-readable)

ux-analyze https://example.com --format json

• Raw analysis data
• Perfect for CI/CD integration
• Parseable by other tools

HTML (Human-readable)

ux-analyze https://example.com --format html

• Beautiful visual reports
• Screenshots included
• Implementation code embedded

Markdown (Documentation-friendly)

ux-analyze https://example.com --format markdown

• README-compatible format
• Great for documentation
• Version control friendly

Integration Examples

CI/CD Pipeline

# GitHub Actions example
- name: UX Analysis
  run: |
    npx ux-analyst-cli https://my-staging-site.com \
      --format json \
      --output ./ux-reports \
      --quick

    # Upload results as artifacts
- uses: actions/upload-artifact@v3
  with:
    name: ux-analysis
    path: ./ux-reports

NPM Scripts

{
  "scripts": {
    "ux-check": "ux-analyze https://localhost:3000 --quick",
    "ux-full": "ux-analyze https://localhost:3000 --code --accessibility",
    "ux-mobile": "ux-analyze https://localhost:3000 --viewports mobile --quick"
  }
}

Automated Reports

#!/bin/bash
# analyze-sites.sh

sites=(
  "https://example.com"
  "https://staging.example.com"
  "https://dev.example.com"
)

for site in "${sites[@]}"; do
  echo "Analyzing $site..."
  ux-analyze "$site" --format html --output "./reports/$(basename $site)"
done

Features

🚀 Fast Analysis

• Quick mode for CI/CD pipelines
• Progressive analysis with real-time updates

🎯 Comprehensive Reports

• UX recommendations with AI insights
• Accessibility compliance checking
• Multi-viewport screenshot capture

💻 Implementation Ready

• Generate HTML, CSS, JavaScript fixes
• Step-by-step implementation guides
• Copy-paste ready code snippets

🔧 Developer Friendly

• Multiple output formats
• Easy CI/CD integration
• Configurable analysis options

📊 Multiple Viewports

• Desktop, tablet, mobile analysis
• Responsive design insights
• Cross-device compatibility checking

API Integration

The CLI can also be used programmatically:

const { UXAnalyzer } = require('ux-analyst-cli');

const analyzer = new UXAnalyzer({
  ai: { geminiApiKey: process.env.GEMINI_API_KEY }
});

const result = await analyzer.analyze('https://example.com', {
  viewports: ['desktop', 'mobile'],
  includeCodeGeneration: true
});

console.log('UX Score:', result.report.summary.uxScore);

Troubleshooting

Common Issues

"API key is required"

# Set environment variable
export GEMINI_API_KEY="your-key"

# Or use --api-key flag
ux-analyze https://example.com --api-key "your-key"

"Analysis timeout"

# Use quick mode for faster analysis
ux-analyze https://example.com --quick

# Or increase timeout in config

"Permission denied"

# Make sure the CLI is executable
chmod +x bin/ux-analyze.js

# Or run with node directly
node bin/ux-analyze.js https://example.com

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.