TCSS CLI

A powerful command-line interface for the TCSS (Typed CSS) compiler.

Installation

From Source

cargo install --path tcss-cli

From Crates.io (Coming Soon)

cargo install tcss-cli

Quick Start

# Get help
tcss --help

# Check version
tcss --version

# Compile a file
tcss compile styles.tcss

# Watch for changes
tcss watch src/ -o dist/

Usage

Getting Help

Display help information:

# General help
tcss --help
tcss -h

# Command-specific help
tcss compile --help
tcss watch --help
tcss init --help
tcss check --help

Version Information

Display version:

tcss --version
tcss -V

Compile Command

Compile a TCSS file to CSS:

tcss compile input.tcss -o output.css

Options:

• -o, --output <OUTPUT> - Output CSS file (defaults to input with .css extension)
• -m, --minify - Minify the output CSS
• -w, --watch - Watch for changes and recompile
• -v, --verbose - Enable verbose output
• --debug - Enable debug mode

Examples:

# Basic compilation
tcss compile styles.tcss

# Compile with custom output
tcss compile src/main.tcss -o dist/main.css

# Compile and minify
tcss compile styles.tcss -o styles.min.css --minify

# Compile and watch for changes
tcss compile styles.tcss --watch

Watch Command

Watch files or directories for changes and auto-compile:

tcss watch src/ -o dist/

Options:

• -o, --output <OUTPUT> - Output directory for compiled CSS
• -m, --minify - Minify the output CSS
• -v, --verbose - Enable verbose output

Examples:

# Watch current directory
tcss watch

# Watch specific directory
tcss watch src/ -o dist/

# Watch with minification
tcss watch src/ -o dist/ --minify

Init Command

Initialize a new TCSS project:

tcss init my-project

Options:

• -d, --dir <DIR> - Project directory (defaults to project name)
• -v, --verbose - Enable verbose output

Examples:

# Create new project
tcss init my-website

# Create project in specific directory
tcss init my-website -d ~/projects/website

Project Structure:

my-project/
├── src/
│   └── main.tcss      # Example TCSS file
├── dist/              # Compiled CSS output
├── .gitignore
└── README.md

Check Command

Check TCSS files for errors without compiling:

tcss check file1.tcss file2.tcss

Options:

• -v, --verbose - Enable verbose output

Examples:

# Check single file
tcss check styles.tcss

# Check multiple files
tcss check src/*.tcss

# Check with verbose output
tcss check styles.tcss --verbose

Command Aliases

TCSS CLI provides short aliases for frequently used commands:

Command	Alias	Usage
compile	c	tcss c styles.tcss
watch	w	tcss w src/
init	i	tcss i my-project

Examples:

# Using aliases
tcss c styles.tcss -o output.css
tcss w src/ -o dist/
tcss i my-new-project

Global Options

These options work with all commands:

• -v, --verbose - Enable verbose output
• --debug - Enable debug mode (includes verbose)
• -h, --help - Print help information
• -V, --version - Print version information

Verbose Mode

Verbose mode shows additional information about operations:

# Compile with verbose output
tcss compile styles.tcss --verbose

# Watch with verbose output
tcss watch src/ -v

What verbose mode shows:

• File operations (reading/writing)
• File sizes
• Timing information
• Progress updates

Example output:

→ Compiling: styles.tcss
✓ Compiled styles.tcss → styles.css
📄 styles.css - 1.23 KB
⏱ Compilation took 45ms

Debug Mode

Debug mode shows detailed debugging information (automatically includes verbose output):

# Compile with debug output
tcss compile styles.tcss --debug

# Check with debug output
tcss check styles.tcss --debug

What debug mode shows:

• Compilation phases (tokenization, parsing, generation)
• Token and AST node counts
• Internal state and variables
• Detailed timing per phase
• Full error context

Example output:

ℹ TCSS CLI 0.1.0 (debug mode)
DEBUG: Debug mode enabled - showing detailed output
DEBUG: Input file = "styles.tcss"
DEBUG: Phase 1: Tokenization
DEBUG: Generated 42 tokens
DEBUG: Phase 2: Parsing
DEBUG: Parsed 8 AST nodes
DEBUG: Phase 3: CSS Generation
DEBUG: Generated 1234 bytes of CSS
✓ Compiled styles.tcss → styles.css

Use cases:

• Verbose: Development and understanding what's happening
• Debug: Troubleshooting issues and detailed diagnostics

See VERBOSE_DEBUG_MODES.md for complete documentation.

Examples:

# Get help for any command
tcss --help
tcss compile --help

# Check version
tcss --version

# Use verbose mode
tcss compile styles.tcss --verbose

# Combine options
tcss compile styles.tcss -o output.css --minify --verbose

Examples

Basic Workflow

# 1. Create a new project
tcss init my-website
cd my-website

# 2. Edit src/main.tcss
# ... make your changes ...

# 3. Compile to CSS
tcss compile src/main.tcss -o dist/main.css

# 4. Or watch for changes
tcss watch src/ -o dist/

Production Build

# Compile and minify for production
tcss compile src/main.tcss -o dist/main.min.css --minify

Development Workflow

# Watch for changes during development
tcss watch src/ -o dist/ --verbose

CI/CD Integration

# Check files in CI
tcss check src/**/*.tcss

# Build for production
tcss compile src/main.tcss -o dist/main.css --minify

Features

• ✅ Fast Compilation - Compile TCSS to CSS instantly
• ✅ Watch Mode - Auto-compile on file changes
• ✅ Minification - Optimize CSS for production
• ✅ Error Checking - Validate TCSS without compiling
• ✅ Project Scaffolding - Quick project setup
• ✅ Colored Output - Beautiful terminal output
• ✅ Verbose Mode - Detailed compilation info

Testing

The TCSS CLI has comprehensive test coverage with 145+ tests:

# Run all tests
cargo test -p tcss-cli

# Run specific test suite
cargo test -p tcss-cli --test compile_tests
cargo test -p tcss-cli --test check_tests
cargo test -p tcss-cli --test init_tests

# Run with test runner script
./tcss-cli/scripts/run_tests.sh

Test Coverage:

• ✅ 50+ compile command tests
• ✅ 35+ check command tests
• ✅ 25+ init command tests
• ✅ 30+ error handling tests
• ✅ 20+ E2E tests
• ✅ 15+ verbose/debug tests

See docs/TESTING.md for complete testing guide.

License

MIT