# TCSS CLI
A powerful command-line interface for the TCSS (Typed CSS) compiler.
## Installation
### From Source
```bash
cargo install --path tcss-cli
```
### From Crates.io (Coming Soon)
```bash
cargo install tcss-cli
```
## Quick Start
```bash
# 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:
```bash
# 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:
```bash
tcss --version
tcss -V
```
### Compile Command
Compile a TCSS file to CSS:
```bash
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:**
```bash
# 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:
```bash
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:**
```bash
# 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:
```bash
tcss init my-project
```
**Options:**
- `-d, --dir <DIR>` - Project directory (defaults to project name)
- `-v, --verbose` - Enable verbose output
**Examples:**
```bash
# 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:
```bash
tcss check file1.tcss file2.tcss
```
**Options:**
- `-v, --verbose` - Enable verbose output
**Examples:**
```bash
# 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:
| compile | c | `tcss c styles.tcss` |
| watch | w | `tcss w src/` |
| init | i | `tcss i my-project` |
**Examples:**
```bash
# 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:
```bash
# 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):
```bash
# 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](docs/VERBOSE_DEBUG_MODES.md) for complete documentation.
**Examples:**
```bash
# 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
```bash
# 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
```bash
# Compile and minify for production
tcss compile src/main.tcss -o dist/main.min.css --minify
```
### Development Workflow
```bash
# Watch for changes during development
tcss watch src/ -o dist/ --verbose
```
### CI/CD Integration
```bash
# 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:
```bash
# 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](docs/TESTING.md) for complete testing guide.
## License
MIT