UniSpec CLI

A powerful and user-friendly command-line interface for UniSpec specifications. Validate, normalize, diff, and convert UniSpec files with ease.

Features

• 🔍 Validate - Check UniSpec specifications against the official schema
• 🔧 Normalize - Apply normalization rules to ensure consistency
• 📊 Diff - Compare two specifications and see detailed differences
• 🔄 Convert - Convert between JSON and YAML formats
• 🎨 Beautiful Output - Colored, formatted output with emojis for better UX
• ⚡ Fast - Built on top of the performant @unispechq/unispec-core
• 🧪 Well Tested - Comprehensive test suite ensuring reliability

Installation

Global Installation

npm install -g @unispechq/unispec-cli

Local Installation

npm install --save-dev @unispechq/unispec-cli

Using npx (no installation needed)

npx @unispechq/unispec-cli <command>

Quick Start

# Validate a specification
unispec validate api-spec.json

# Normalize a specification
unispec normalize api-spec.json --output normalized.json

# Compare two specifications
unispec diff old-spec.json new-spec.json

# Convert JSON to YAML
unispec convert api-spec.json --format yaml --output api-spec.yaml

Commands

Validate

Validate UniSpec specifications against the official schema.

unispec validate <file> [options]

Options:

• -s, --schema - Validate schema only
• -c, --config - Validate configuration only
• -t, --tests - Validate tests only
• -f, --format <format> - Output format: json, yaml, table (default: table)
• --verbose - Enable verbose output

Examples:

# Basic validation
unispec validate api-spec.json

# JSON output for CI/CD
unispec validate api-spec.json --format json

# Validate with verbose output
unispec validate api-spec.json --verbose

Exit Codes:

• 0 - Validation successful
• 1 - Validation failed or error occurred

Normalize

Apply normalization rules to ensure consistency across specifications.

unispec normalize <file> [options]

Options:

• -o, --output <path> - Output file path (default: overwrite input)
• -f, --format <format> - Output format: json, yaml (default: json)
• --backup - Create backup of original file
• --indent <size> - JSON indentation size (default: 2)

Examples:

# Normalize in place
unispec normalize api-spec.json

# Normalize to new file with backup
unispec normalize api-spec.json --output normalized.json --backup

# Convert to YAML during normalization
unispec normalize api-spec.json --format yaml --output api-spec.yaml

Diff

Compare two UniSpec specifications and see detailed differences.

unispec diff <file1> <file2> [options]

Options:

• -f, --format <format> - Output format: table, json, summary (default: table)
• --enhanced - Use enhanced diff algorithm
• --context <lines> - Number of context lines for enhanced diff (default: 3)
• --ignore <fields> - Comma-separated list of fields to ignore

Examples:

# Basic comparison
unispec diff old-spec.json new-spec.json

# Summary view
unispec diff old-spec.json new-spec.json --format summary

# JSON output for automation
unispec diff old-spec.json new-spec.json --format json

# Ignore specific fields
unispec diff old-spec.json new-spec.json --ignore "info.version,service.name"

Exit Codes:

• 0 - No differences found
• 1 - Differences found or error occurred

Convert

Convert UniSpec specifications between JSON and YAML formats.

unispec convert <file> [options]

Options:

• -o, --output <path> - Output file path
• -f, --format <format> - Target format: json, yaml (default: json)
• --indent <size> - JSON indentation size (default: 2)
• --backup - Create backup of original file

Examples:

# Convert JSON to YAML
unispec convert api-spec.json --format yaml --output api-spec.yaml

# Convert YAML to JSON with custom indentation
unispec convert api-spec.yaml --format json --indent 4 --output api-spec.json

# Convert with backup
unispec convert api-spec.json --format yaml --backup

Global Options

These options are available for all commands:

• --config <path> - Path to configuration file (default: unispec.config.json)
• --verbose - Enable verbose output
• --no-color - Disable colored output
• -v, --version - Display version number
• -h, --help - Display help for command

Configuration

You can create a unispec.config.json file in your project root to set default options:

{
  "validate": {
    "format": "json",
    "strict": true
  },
  "normalize": {
    "backup": true,
    "indent": 2
  },
  "diff": {
    "format": "summary",
    "ignore": ["info.version"]
  },
  "convert": {
    "format": "yaml",
    "backup": true
  }
}

Examples

CI/CD Integration

#!/bin/bash
# Validate all spec files in a directory
for file in specs/*.json; do
  if ! unispec validate "$file" --format json; then
    echo "Validation failed for $file"
    exit 1
  fi
done

# Compare specs before deployment
if unispec diff current-spec.json new-spec.json; then
  echo "No changes detected"
else
  echo "Changes detected, review required"
  exit 1
fi

Git Hook Example

#!/bin/sh
# .git/hooks/pre-commit
echo "Validating UniSpec files..."

for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.json$\|\.yaml$'); do
  if ! unispec validate "$file"; then
    echo "❌ Validation failed for $file"
    exit 1
  fi
done

echo "✅ All files validated successfully"

Development Workflow

# Normalize all specs
find specs -name "*.json" -exec unispec normalize {} --backup \;

# Convert all to YAML
for file in specs/*.json; do
  unispec convert "$file" --format yaml --output "${file%.json}.yaml"
done

# Check for changes
unispec diff specs/v1/api.json specs/v2/api.json --format summary

API Reference

Programmatic Usage

You can also use the CLI programmatically:

import { validateCommand, normalizeCommand, diffCommand, convertCommand } from '@unispechq/unispec-cli';

// Commands are Commander.js instances
// Use them in your own CLI tools

Error Handling

The CLI provides clear error messages and appropriate exit codes:

• Validation Errors - Detailed schema violations with paths and line numbers
• File System Errors - Clear messages for missing files or permission issues
• Format Errors - Helpful messages for invalid JSON/YAML syntax

All errors include:

• Clear description
• File path (when applicable)
• Line/column numbers (when available)
• Suggestions for resolution

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/unispechq/unispec-platform.git
cd unispec-platform

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run in development mode
npm run dev -- validate test-spec.json

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

Related Projects

• @unispechq/unispec-core - Core UniSpec library
• @unispechq/unispec-spec - UniSpec specification
• UniSpec Registry - Official specification registry

Made with ❤️ by the UniSpec team