CLI Reference

Utah provides a comprehensive command-line interface for compiling, running, formatting, and managing Utah scripts. The CLI is built with .NET 9 and offers robust error handling and clear feedback.

✨ Direct Execution

Utah supports direct execution of .shx files and commands without requiring explicit command prefixes:

# Run a .shx file directly (no 'run' command needed!)
utah script.shx

# Execute a remote .shx file (explicit opt-in)
utah https://example.com/script.shx --allow-remote

# Execute commands directly
utah -c "echo('Hello, World!')"
utah --command "os.isInstalled('git')"

This makes Utah feel more like traditional script interpreters (python script.py, node script.js, etc.) while maintaining full backward compatibility with the explicit run command.

Quick Start

# Install Utah
curl -sL https://utahshx.com/install.sh | sudo bash

# Compile a script
utah compile script.shx

# Run a script directly
utah script.shx

# Run commands directly
utah -c "echo('Hello from Utah!')"

# Format a single script
utah format script.shx

# Format all .shx files in project recursively
utah format --in-place

Available Commands

Command	Description	Usage
<file.shx>	Direct execution	utah <file.shx>
-c, --command	Direct command	utah -c <command>
compile	Transpile .shx to .sh	utah compile <file.shx> [-o, --output <output.sh>]
debug	Compile with source maps	utah debug <file.shx> [-o, --output <output.sh>]
run	Compile and execute	utah run <file.shx> or utah run -c <command>
format	Format source code	utah format [file.shx] [options]
lsp	Language server	utah lsp
version	Show version info	utah version

When no file is specified, utah format automatically processes all .shx files recursively from the current directory.

Command Details

Compile Command

Transpiles Utah (.shx) source files into bash (.sh) scripts:

utah compile script.shx                        # Creates script.sh
utah compile script.shx -o custom.sh           # Creates custom.sh
utah compile script.shx --output custom.sh     # Creates custom.sh

Features:

• Resolves import statements automatically
• Generates clean, readable bash code
• Preserves comments and structure
• Error reporting with line numbers

Debug Command

Compiles Utah scripts with source-map comments that trace each bash line back to its .shx source:

utah debug script.shx                          # Creates script.sh with source maps
utah debug script.shx -o debug-output.sh       # Custom output path
utah debug script.shx --output debug-output.sh # Custom output path (long form)

Each compiled statement is preceded by a # [shx:<line>] <source> comment:

# [shx:1] let name: string = "Utah";
name="Utah"
# [shx:2] console.log("Hello");
echo "Hello"

Features:

• Same transpilation as compile with embedded source-map comments
• Trace runtime bash errors back to .shx line numbers
• Comments are valid bash — debug scripts run identically to regular compiled scripts
• Works with nested statements inside functions, loops, and conditionals

Run Command

Compiles and immediately executes Utah scripts or commands:

# Run a .shx file
utah run script.shx

# Run a remote .shx file
utah run --allow-remote https://example.com/script.shx

# Run a single command directly
utah run -c "console.log('Hello, World!')"
utah run --command "utility.uuid()"

# More command examples
utah run -c "os.isInstalled('git')"
utah run --command "fs.exists('/path/to/file')"

Features:

• Execute .shx files directly
• Explicit opt-in for executing remote .shx URLs
• Run single commands without creating files
• Temporary compilation (no .sh file created for direct commands)
• Real-time output streaming
• Error propagation from bash execution
• Automatic cleanup of temporary files

Options:

• utah <file.shx>: Execute a .shx file directly
• utah <url> --allow-remote: Execute a remote .shx file directly
• utah -c <command>: Execute a single command directly
• utah --command <command>: Execute a single command directly (long form)
• utah run <file.shx>: Execute a .shx file
• utah run --allow-remote <url>: Execute a remote .shx file
• utah run -c <command>: Execute a single command directly
• utah run --command <command>: Execute a single command directly

Format Command

Formats Utah source code according to EditorConfig rules:

utah format                               # Format all .shx files recursively
utah format --in-place                    # Format all files in place
utah format --check                       # Check all files formatting
utah format script.shx                    # Creates script.formatted.shx
utah format script.shx -o clean.shx       # Creates clean.shx
utah format script.shx --output clean.shx # Creates clean.shx (long form)
utah format script.shx --in-place         # Overwrites script.shx
utah format script.shx --check            # Exit 1 if not formatted

Options:

• No file specified: Format all .shx files recursively
• -o, --output <file>: Specify output file (single file only)
• --in-place: Overwrite original file(s)
• --check: Check formatting without modifying

Language Server

Provides completion support for editors that integrate with utah lsp:

utah lsp

Current feature:

• Code completion for Utah namespaces and member access

Syntax highlighting comes from editor grammars (such as the VS Code extension), not from the language server itself.

Version Information

Shows detailed version and runtime information:

utah version
utah --version
utah -v

Output includes:

• Utah version number
• .NET runtime version
• Operating system details
• Architecture information

Error Handling

Utah CLI provides clear error messages and appropriate exit codes:

# Compilation errors
utah compile broken.shx
# ❌ Compilation failed: Syntax error at line 5: Expected ';'

# File not found
utah run missing.shx
# File not found: missing.shx

# Format check failure
utah format messy.shx --check
# ❌ File is not formatted: messy.shx
# Exit code: 1

Integration Examples

Build Scripts

#!/bin/bash
# Build script using Utah CLI

echo "Building Utah scripts..."

for file in src/*.shx; do
  if utah compile "$file" -o "dist/$(basename "$file" .shx).sh"; then
    echo "✅ Compiled: $file"
  else
    echo "❌ Failed: $file"
    exit 1
  fi
done

echo "Build completed successfully"

CI/CD Pipeline

# GitHub Actions example
name: Utah CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Utah
        run: |
          curl -sL https://utahshx.com/install.sh | sudo bash

      - name: Check formatting
        run: |
          for file in src/*.shx; do
            utah format "$file" --check
          done

      - name: Compile all scripts
        run: |
          for file in src/*.shx; do
            utah compile "$file"
          done

      - name: Run tests
        run: |
          for file in tests/*.shx; do
            utah run "$file"
          done

VS Code Integration

Utah includes a VS Code extension that uses the language server:

{
  "recommendations": [
    "utah-lang.utah-language-support"
  ]
}

Features provided today:

• Syntax highlighting for .shx files
• File icons and Utah language association
• LSP-backed code completion for built-in namespaces and common member access
• Use utah format from VS Code tasks or the integrated terminal for formatting

Advanced IDE features such as diagnostics, hover, go-to-definition, references, and a formatting provider are still in progress.

Advanced Usage

Import Resolution

Utah automatically resolves import statements during compilation:

// main.shx
import "utils/helpers.shx";
import "config/settings.shx";

// Code using imported functions

utah compile main.shx
# Automatically includes helpers.shx and settings.shx

Batch Operations

# Compile all .shx files in a directory
find . -name "*.shx" -exec utah compile {} \;

# Format all files recursively (recommended)
utah format --in-place

# Check all files are formatted recursively (recommended)
utah format --check

# Format with find
find . -name "*.shx" -exec utah format {} --in-place \;

Note: The new utah format without a filename automatically processes all .shx files recursively, providing better progress reporting and error handling than the find approach.

Output Redirection

# Capture compilation output
utah compile script.shx 2> errors.log

# Run with output logging
utah run script.shx > output.log 2>&1

Troubleshooting

Common Issues

• Problem: Command not found

utah: command not found

Solution: Ensure Utah is installed and in your PATH

# Reinstall Utah
curl -sL https://utahshx.com/install.sh | sudo bash

• Problem: Compilation fails with syntax error

❌ Compilation failed: Syntax error at line 5: Expected ';'

Solution: Check syntax around the reported line number

• Problem: Permission denied when running

❌ Unexpected error: Permission denied

Solution: Check file permissions and ensure bash is executable

chmod +x generated_script.sh

• Problem: Import file not found

❌ Compilation failed: Import file not found: utils/helper.shx

Solution: Verify import paths are relative to the main file

Debug Mode

Use the debug command to compile with source-map comments for troubleshooting:

# Compile with source-map comments
utah debug script.shx

# Combine with bash tracing for maximum visibility
utah debug script.shx -o debug-script.sh
bash -x debug-script.sh

See the Debug Command documentation for details.

Getting Help

# Show usage information
utah

# Show command-specific help
utah compile
utah debug
utah format
utah run

Performance Considerations

Compilation Speed

• Small files (< 100 lines): < 100ms
• Medium files (100-1000 lines): < 500ms
• Large files (1000+ lines): < 2s

Memory Usage

• Typical usage: 10-50MB RAM
• Large projects: 100-200MB RAM
• Language server: 50-100MB RAM

Optimization Tips

1. Use specific imports: Only import what you need
2. Avoid deep nesting: Keep import chains shallow
3. Batch operations: Compile multiple files together when possible
4. Cache results: Compiled .sh files don't need recompilation unless .shx changes

Related Documentation

• Installation Guide - Setup and installation
• Language Features - Utah syntax and features
• Functions Reference - Built-in function documentation
• VS Code Extension - IDE integration details