ursamu/docs/CLI_REFERENCE.md

Ursamu - Modular MUD Engine with sandboxed scripting and plugin system

# Ursamu CLI Reference

The Ursamu CLI is a comprehensive command-line interface for developing, debugging, and managing MUD (Multi-User Dungeon) projects. It provides tools for script management, interactive debugging, performance profiling, and complete project lifecycle management.

## Table of Contents

- [Installation & Quick Start](#installation--quick-start)
- [Global Options](#global-options)
- [Command Overview](#command-overview)
- [Script Commands](#script-commands)
- [Debug Commands](#debug-commands)
- [Profile Commands](#profile-commands)
- [Project Commands](#project-commands)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [Tips & Best Practices](#tips--best-practices)

## Installation & Quick Start

### Installation
```bash
# Use with npx (recommended)
npx ursamu --help

# Or install globally
npm install -g ursamu
ursamu --help
```

### Quick Start
```bash
# Create a new MUD project
ursamu project init my-mud-game

# Create your first script
ursamu script create welcome -t basic

# Test the script
ursamu script test welcome.mud

# Start debugging
ursamu debug start welcome.mud --entry
```

## Global Options

The following options are available for all commands:

| Option | Description |
|--------|-------------|
| `-v, --verbose` | Enable verbose logging and detailed output |
| `-c, --config <path>` | Specify custom configuration file path |
| `--no-color` | Disable colored output |
| `-V, --version` | Display version information |
| `-h, --help` | Display help information |

**Example:**
```bash
ursamu script list --verbose --no-color
ursamu -c ./custom-config.json project info
```

## Command Overview

| Command | Description |
|---------|-------------|
| [`script`](#script-commands) | Script management and development |
| [`debug`](#debug-commands) | Interactive debugging and testing |
| [`profile`](#profile-commands) | Performance profiling and analysis |
| [`project`](#project-commands) | Project lifecycle management |

---

## Script Commands

**Usage:** `ursamu script <subcommand> [options]`

The script command provides comprehensive script management capabilities including creation, validation, deployment, and monitoring.

### 🎯 **TypeScript Support**

Ursamu now includes full TypeScript support for script development:

- **Automatic Compilation**: `.ts` files are compiled to JavaScript with hot-reload
- **Type Definitions**: Comprehensive MUD-specific type definitions included
- **Rich Templates**: All templates can be generated as TypeScript with `--typescript` flag
- **Error Reporting**: TypeScript compilation errors shown with line numbers
- **Source Maps**: Inline source maps for debugging support

**TypeScript Features:**
- Interface definitions for `Player`, `Room`, `Item`, `GameContext`, `GameAPI`
- Type-safe function signatures and return types
- Optional strict typing (configurable)
- Full IntelliSense support in compatible editors

### `script create [name]`
Create a new script from a template.

**Options:**
- `-t, --template <type>` - Template type: `basic`, `combat`, `npc`, `room`, `command`, `event` (default: basic)
- `--typescript` - Create TypeScript (.ts) file with full type annotations
- `-p, --path <path>` - Custom script path
- `--force` - Overwrite existing script without confirmation

**Examples:**
```bash
# Create basic script
ursamu script create hello-world

# Create TypeScript combat script
ursamu script create combat-system -t combat --typescript

# Create TypeScript script with custom path
ursamu script create combat-system -t combat --typescript -p ./game-scripts/

# Force overwrite existing script
ursamu script create player-actions --force
```

### `script list` (alias: `ls`)
List all available scripts with their status and information.

**Options:**
- `-l, --long` - Show detailed information (size, modified date, dependencies)
- `-s, --status` - Show script execution status and health
- `-f, --filter <pattern>` - Filter scripts by name pattern (supports wildcards)

**Examples:**
```bash
# Basic list
ursamu script list

# Detailed list with status
ursamu script ls -l -s

# Filter combat-related scripts
ursamu script list -f "combat*"
```

### `script validate <script>`
Validate script syntax, dependencies, and security requirements.

**Options:**
- `--strict` - Enable strict validation mode (more rigorous checks)
- `--deps` - Check and validate all dependencies
- `--security` - Run security analysis

**Examples:**
```bash
# Basic validation
ursamu script validate combat.mud

# Strict validation with dependency checking
ursamu script validate combat.mud --strict --deps --security
```

### `script deploy <script>`
Deploy script to the running server with hot-reload capabilities.

**Options:**
- `--no-validate` - Skip pre-deployment validation
- `--no-backup` - Skip creating backup before deployment
- `--force` - Force deployment even with validation warnings
- `-w, --watch` - Watch for file changes and auto-redeploy

**Examples:**
```bash
# Deploy with validation and backup
ursamu script deploy combat.mud

# Deploy and watch for changes
ursamu script deploy combat.mud --watch

# Force deploy without validation
ursamu script deploy experimental.mud --force --no-validate
```

### `script test <script>`
Execute script in a controlled test environment.

**Options:**
- `-i, --input <data>` - Provide test input data as JSON string
- `-c, --context <context>` - Set execution context (player, room, global)
- `--timeout <ms>` - Execution timeout in milliseconds (default: 5000)
- `--mock` - Use mock data for external dependencies

**Examples:**
```bash
# Basic test
ursamu script test combat.mud

# Test with input data
ursamu script test combat.mud -i '{"player": "testUser", "weapon": "sword"}'

# Test with extended timeout
ursamu script test long-running.mud --timeout 30000
```

### `script watch`
Monitor script directory for changes and automatically deploy updates.

**Options:**
- `-p, --path <path>` - Path to watch (default: configured scriptPath)
- `--no-validate` - Skip validation on file changes
- `--debounce <ms>` - Debounce delay in milliseconds (default: 1000)
- `--exclude <pattern>` - Exclude files matching pattern

**Examples:**
```bash
# Watch default script directory
ursamu script watch

# Watch custom path with longer debounce
ursamu script watch -p ./game-scripts --debounce 2000

# Watch without validation
ursamu script watch --no-validate
```

### `script edit <script>`
Open script in your preferred editor.

**Options:**
- `-e, --editor <editor>` - Specify editor command (default: system default)

**Examples:**
```bash
# Open with default editor
ursamu script edit combat.mud

# Open with specific editor
ursamu script edit combat.mud -e "code --wait"
```

### `script remove <script>` (alias: `rm`)
Remove script from the project.

**Options:**
- `--backup` - Create backup before removal
- `--force` - Skip confirmation prompt

**Examples:**
```bash
# Remove with confirmation
ursamu script remove old-script.mud

# Remove with backup, no confirmation
ursamu script rm deprecated.mud --backup --force
```

---

## Debug Commands

**Usage:** `ursamu debug <subcommand> [options]`

The debug command provides full interactive debugging capabilities including breakpoints, step-through debugging, variable inspection, and expression evaluation.

### `debug start <script>`
Start a new debugging session for the specified script.

**Options:**
- `-b, --breakpoint <line>` - Set initial breakpoint at line number
- `-c, --condition <expr>` - Set conditional breakpoint
- `--entry` - Break on script entry point
- `--attach` - Attach to running script instance

**Examples:**
```bash
# Start debugging with entry break
ursamu debug start combat.mud --entry

# Start with breakpoint at line 25
ursamu debug start combat.mud -b 25

# Start with conditional breakpoint
ursamu debug start combat.mud -b 10 -c "health < 50"
```

### `debug stop`
Stop the current debugging session and cleanup resources.

**Examples:**
```bash
ursamu debug stop
```

### `debug break <line>` (alias: `bp`)
Set a breakpoint at the specified line.

**Options:**
- `-c, --condition <expr>` - Conditional breakpoint expression
- `-f, --file <file>` - Specify source file if different from current
- `--temp` - Create temporary breakpoint (removed after first hit)

**Examples:**
```bash
# Set simple breakpoint
ursamu debug break 15

# Set conditional breakpoint
ursamu debug bp 20 -c "player.level > 10"

# Set breakpoint in specific file
ursamu debug break 5 -f utils.mud --temp
```

### `debug clear <id>`
Clear a breakpoint by its ID.

**Examples:**
```bash
# Clear specific breakpoint
ursamu debug clear bp_10_1234567890

# Clear all breakpoints
ursamu debug clear all
```

### `debug list` (alias: `ls`)
List all active breakpoints with their details.

**Examples:**
```bash
# List all breakpoints
ursamu debug list

# List with details
ursamu debug ls --verbose
```

### `debug continue` (alias: `c`)
Continue script execution until next breakpoint or completion.

**Examples:**
```bash
ursamu debug continue
ursamu debug c
```

### `debug step` (alias: `s`)
Step into the next statement (enters function calls).

**Examples:**
```bash
ursamu debug step
ursamu debug s
```

### `debug next` (alias: `n`)
Step over the next statement (doesn't enter function calls).

**Examples:**
```bash
ursamu debug next
ursamu debug n
```

### `debug out` (alias: `o`)
Step out of the current function and return to caller.

**Examples:**
```bash
ursamu debug out
ursamu debug o
```

### `debug stack`
Display the current call stack.

**Options:**
- `-v, --verbose` - Show local variables for each frame
- `-d, --depth <n>` - Limit stack depth display

**Examples:**
```bash
# Show call stack
ursamu debug stack

# Show stack with variables
ursamu debug stack -v

# Show top 5 frames only
ursamu debug stack -d 5
```

### `debug vars [pattern]`
Show variables in the current scope.

**Examples:**
```bash
# Show all variables
ursamu debug vars

# Show variables matching pattern
ursamu debug vars player*

# Show global variables
ursamu debug vars --global
```

### `debug eval <expression>`
Evaluate an expression in the current debugging context.

**Examples:**
```bash
# Evaluate simple expression
ursamu debug eval "player.health"

# Evaluate complex expression
ursamu debug eval "Math.max(player.strength, player.dexterity)"

# Modify variables
ursamu debug eval "player.health = 100"
```

### `debug watch <variable>`
Watch a variable for changes during execution.

**Examples:**
```bash
# Watch a variable
ursamu debug watch player.health

# Watch complex expression
ursamu debug watch "player.stats.totalDamage"
```

### `debug interactive [script]` (alias: `i`)
Enter interactive debugging mode with a REPL interface.

**Examples:**
```bash
# Enter interactive mode
ursamu debug interactive

# Start interactive session with script
ursamu debug i combat.mud
```

### `debug history`
Show debugging session command history.

**Options:**
- `-n, --lines <count>` - Number of history entries to show (default: 20)
- `--clear` - Clear command history

**Examples:**
```bash
# Show recent history
ursamu debug history

# Show last 50 commands
ursamu debug history -n 50
```

---

## Profile Commands

**Usage:** `ursamu profile <subcommand> [options]`

The profile command provides comprehensive performance analysis tools including CPU profiling, memory analysis, benchmarking, and execution tracing.

### `profile start <script>`
Start profiling a script's execution.

**Options:**
- `-i, --interval <ms>` - Sampling interval in milliseconds (default: 100)
- `-d, --duration <ms>` - Maximum profiling duration (default: 60000)
- `--memory` - Enable memory profiling
- `--cpu` - Enable CPU profiling
- `--functions` - Profile individual function calls
- `--heap` - Include heap snapshots

**Examples:**
```bash
# Basic CPU profiling
ursamu profile start combat.mud

# Comprehensive profiling
ursamu profile start combat.mud --memory --cpu --functions --heap

# High-resolution profiling
ursamu profile start intensive.mud -i 10 -d 120000
```

### `profile stop`
Stop the current profiling session and save results.

**Options:**
- `-r, --report` - Generate report immediately
- `-o, --output <file>` - Save profile data to specific file
- `--format <type>` - Output format: json, binary (default: binary)

**Examples:**
```bash
# Stop profiling
ursamu profile stop

# Stop and generate immediate report
ursamu profile stop -r -o profile-$(date +%Y%m%d).prof
```

### `profile report [script]`
Generate a detailed profiling report from collected data.

**Options:**
- `-f, --format <type>` - Report format: `text`, `json`, `html` (default: text)
- `-o, --output <file>` - Output file path
- `--top <n>` - Show top N functions by time (default: 10)
- `--threshold <ms>` - Minimum time threshold to display (default: 1)
- `--sort <field>` - Sort by: time, calls, memory (default: time)

**Examples:**
```bash
# Generate text report
ursamu profile report combat.mud

# Generate HTML report
ursamu profile report combat.mud -f html -o report.html --top 20

# Generate JSON report with all functions above 5ms
ursamu profile report -f json --threshold 5
```

### `profile benchmark <script>` (alias: `bench`)
Run performance benchmarks on a script.

**Options:**
- `-n, --runs <count>` - Number of benchmark runs (default: 10)
- `-w, --warmup <count>` - Number of warmup runs (default: 3)
- `-i, --input <data>` - Benchmark input data as JSON
- `--compare <baseline>` - Compare against baseline results
- `--save <name>` - Save results as baseline

**Examples:**
```bash
# Basic benchmark
ursamu profile benchmark combat.mud

# Comprehensive benchmark
ursamu profile bench combat.mud -n 100 -w 10 --save baseline-v1

# Compare with baseline
ursamu profile benchmark combat.mud -n 50 --compare baseline-v1
```

### `profile memory <script>`
Analyze memory usage patterns and detect potential leaks.

**Options:**
- `-d, --duration <ms>` - Analysis duration (default: 30000)
- `--gc` - Include garbage collection analysis
- `--leaks` - Enable memory leak detection
- `--snapshots <count>` - Number of heap snapshots to take
- `--threshold <bytes>` - Memory threshold for alerts

**Examples:**
```bash
# Basic memory analysis
ursamu profile memory combat.mud

# Comprehensive memory analysis with leak detection
ursamu profile memory combat.mud --gc --leaks --snapshots 10

# Long-term memory monitoring
ursamu profile memory long-running.mud -d 300000
```

### `profile cpu <script>`
Analyze CPU usage patterns and identify performance bottlenecks.

**Options:**
- `-d, --duration <ms>` - Analysis duration (default: 30000)
- `-s, --samples <count>` - Number of CPU samples (default: 1000)
- `--threads` - Include thread analysis
- `--syscalls` - Track system calls

**Examples:**
```bash
# Basic CPU analysis
ursamu profile cpu combat.mud

# Detailed CPU profiling
ursamu profile cpu intensive.mud -d 60000 -s 5000 --threads --syscalls
```

### `profile trace <script>`
Trace script execution flow and function calls.

**Options:**
- `-v, --verbose` - Verbose tracing output
- `--filter <pattern>` - Filter functions by name pattern
- `--depth <n>` - Maximum call depth to trace (default: 10)
- `--time` - Include timing information
- `--args` - Show function arguments

**Examples:**
```bash
# Basic execution tracing
ursamu profile trace combat.mud

# Detailed tracing with timing
ursamu profile trace combat.mud -v --time --args --depth 20

# Filter specific functions
ursamu profile trace combat.mud --filter "attack*,defend*"
```

### `profile compare <baseline> <comparison>`
Compare two profiling results to identify performance differences.

**Options:**
- `-m, --metric <type>` - Comparison metric: time, memory, calls (default: time)
- `-t, --threshold <percent>` - Significance threshold percentage (default: 5)
- `--format <type>` - Output format: text, html, json (default: text)

**Examples:**
```bash
# Compare performance profiles
ursamu profile compare baseline.prof current.prof

# Compare memory usage with custom threshold
ursamu profile compare old.prof new.prof -m memory -t 10

# Generate HTML comparison report
ursamu profile compare v1.prof v2.prof --format html -o comparison.html
```

### `profile list`
List saved profiling reports and data files.

**Options:**
- `-s, --sort <field>` - Sort by: date, script, duration (default: date)
- `-n, --limit <count>` - Limit number of results (default: 20)
- `--filter <pattern>` - Filter by script name pattern

**Examples:**
```bash
# List recent profiles
ursamu profile list

# List profiles sorted by script name
ursamu profile list -s script -n 50

# Filter combat-related profiles
ursamu profile list --filter "combat*"
```

### `profile delete <pattern>`
Delete profiling reports matching the specified pattern.

**Options:**
- `--force` - Skip confirmation prompts
- `--older-than <days>` - Delete files older than N days

**Examples:**
```bash
# Delete specific profiles
ursamu profile delete "combat*"

# Delete old profiles without confirmation
ursamu profile delete "*" --older-than 30 --force
```

---

## Project Commands

**Usage:** `ursamu project <subcommand> [options]`

The project command manages the complete lifecycle of MUD projects including initialization, configuration, building, deployment, and maintenance.

### `project init [name]`
Initialize a new MUD project with directory structure and configuration.

**Options:**
- `-t, --template <type>` - Project template: `basic`, `advanced`, `combat-focused`, `social-focused` (default: basic)
- `--skip-deps` - Skip dependency installation
- `--force` - Overwrite existing project files
- `--git` - Initialize git repository
- `--author <name>` - Set project author

**Examples:**
```bash
# Create basic project
ursamu project init my-mud-game

# Create advanced project with git
ursamu project init epic-mud -t advanced --git --author "Your Name"

# Create combat-focused project
ursamu project init combat-mud -t combat-focused

# Force recreate existing project
ursamu project init existing-project --force
```

### `project info`
Display comprehensive project information and status.

**Options:**
- `-v, --verbose` - Show detailed configuration and statistics
- `--health` - Include server health information
- `--deps` - Show dependency information

**Examples:**
```bash
# Basic project info
ursamu project info

# Detailed project status
ursamu project info -v --health --deps
```

### `project validate`
Validate project configuration, scripts, and dependencies.

**Options:**
- `--fix` - Automatically fix detected issues where possible
- `--strict` - Use strict validation rules
- `--report <file>` - Save validation report to file

**Examples:**
```bash
# Basic validation
ursamu project validate

# Validate and fix issues
ursamu project validate --fix --strict

# Generate validation report
ursamu project validate --report validation-report.html
```

### `project build`
Build and compile all project scripts and assets.

**Options:**
- `-w, --watch` - Watch for changes and rebuild automatically
- `-o, --output <path>` - Output directory (default: ./build)
- `--minify` - Minify compiled scripts
- `--sourcemap` - Generate source maps
- `--clean` - Clean output directory before building

**Examples:**
```bash
# Build project
ursamu project build

# Build with watching and minification
ursamu project build -w --minify --sourcemap

# Build to custom directory
ursamu project build -o ./dist --clean
```

### `project clean`
Clean build artifacts and temporary files.

**Options:**
- `--all` - Remove all generated files including logs
- `--cache` - Clear compilation cache
- `--deps` - Clean dependency cache

**Examples:**
```bash
# Basic clean
ursamu project clean

# Complete cleanup
ursamu project clean --all --cache --deps
```

### `project deploy`
Deploy project to target server environment.

**Options:**
- `-e, --env <environment>` - Target environment: development, staging, production
- `--dry-run` - Simulate deployment without making changes
- `--backup` - Create backup before deployment
- `--rollback` - Enable automatic rollback on failure

**Examples:**
```bash
# Deploy to development
ursamu project deploy

# Deploy to production with backup
ursamu project deploy -e production --backup --rollback

# Simulate production deployment
ursamu project deploy -e production --dry-run
```

### `project config [key] [value]`
Manage project configuration settings.

**Options:**
- `-l, --list` - List all configuration keys and values
- `-g, --global` - Use global configuration instead of project-specific
- `--unset <key>` - Remove configuration key
- `--reset` - Reset to default configuration

**Examples:**
```bash
# List all configuration
ursamu project config -l

# Set server URL
ursamu project config serverUrl "https://my-mud-server.com"

# Get specific config value
ursamu project config debuggerPort

# Reset configuration
ursamu project config --reset
```

### `project docs`
Generate project documentation from scripts and comments.

**Options:**
- `-o, --output <path>` - Output directory (default: ./docs)
- `-f, --format <type>` - Documentation format: html, markdown (default: html)
- `--theme <theme>` - Documentation theme
- `--private` - Include private/internal documentation

**Examples:**
```bash
# Generate HTML documentation
ursamu project docs

# Generate Markdown docs
ursamu project docs -f markdown -o ./md-docs

# Generate complete documentation
ursamu project docs --private --theme dark
```

### `project health`
Check project and connected server health status.

**Options:**
- `-v, --verbose` - Detailed health information
- `--fix` - Attempt to fix detected issues
- `--timeout <ms>` - Health check timeout (default: 10000)

**Examples:**
```bash
# Basic health check
ursamu project health

# Detailed health check with fixes
ursamu project health -v --fix
```

### `project backup`
Create a backup of the entire project.

**Options:**
- `-o, --output <path>` - Backup file path
- `--include-build` - Include build artifacts in backup
- `--include-logs` - Include log files in backup
- `--compress` - Compress backup archive

**Examples:**
```bash
# Basic backup
ursamu project backup

# Complete backup with compression
ursamu project backup -o backup-$(date +%Y%m%d).tar.gz --include-build --include-logs --compress
```

### `project restore <backup-file>`
Restore project from a backup archive.

**Options:**
- `--force` - Overwrite existing files without confirmation
- `--partial` - Allow partial restoration if some files fail
- `--preview` - Show what would be restored without doing it

**Examples:**
```bash
# Restore from backup
ursamu project restore backup-20231215.tar.gz

# Preview restoration
ursamu project restore backup-20231215.tar.gz --preview

# Force restoration
ursamu project restore backup-20231215.tar.gz --force
```

---

## Configuration

The Ursamu CLI uses a hierarchical configuration system with the following priority order:

1. Command-line options
2. Project-specific configuration (`.ursamu/config.json`)
3. User configuration (`~/.ursamu/config.json`)
4. Global defaults

### Default Configuration

```json
{
  "serverHost": "localhost",
  "serverPort": 8080,
  "debuggerPort": 9090,
  "scriptPath": "./scripts",
  "templatePath": "./templates",
  "buildPath": "./build",
  "hotReload": true,
  "autoSave": true,
  "verbose": false,
  "colorOutput": true,
  "maxLogLines": 1000,
  "timeout": 30000,
  "retryAttempts": 3,
  "editor": "auto",
  "backupOnDeploy": true,
  "validateBeforeDeploy": true
}
```

### Configuration Management

```bash
# View current configuration
ursamu project config -l

# Set configuration values
ursamu project config serverPort 9000
ursamu project config hotReload true

# Use custom config file
ursamu -c ./my-config.json script list

# Reset to defaults
ursamu project config --reset
```

---

## Usage Examples

### TypeScript Development Workflow

```bash
# 1. Create TypeScript MUD project
ursamu project init my-typescript-mud -t advanced

# 2. Create TypeScript scripts with type safety
ursamu script create player-manager -t basic --typescript
ursamu script create spell-system -t combat --typescript

# 3. The generated TypeScript includes full type definitions:
# interface Player, Room, GameContext, etc.

# 4. Watch and auto-compile TypeScript files
ursamu script watch

# 5. TypeScript files (.ts) are automatically compiled to JavaScript (.js)
# Compilation errors are shown in real-time with line numbers

# 6. Deploy compiled scripts (hot-reload supported)
ursamu script deploy spell-system.ts --watch
```

### Complete Development Workflow

```bash
# 1. Create new project
ursamu project init my-epic-mud -t advanced --git

# 2. Navigate to project
cd my-epic-mud

# 3. Create initial scripts (with TypeScript)
ursamu script create player-login -t basic --typescript
ursamu script create combat-system -t combat --typescript
ursamu script create dungeon-room -t room --typescript
ursamu script create help-command -t command --typescript
ursamu script create login-event -t event --typescript

# 4. Validate scripts (TypeScript compilation included)
ursamu script validate player-login.ts --strict
ursamu script validate combat-system.ts --deps

# 5. Test scripts (automatically compiled from TypeScript)
ursamu script test player-login.ts -i '{"username":"testuser"}'

# 6. Start development with hot-reload
ursamu script watch --debounce 500

# 7. Debug issues
ursamu debug start combat-system.mud --entry
ursamu debug break 25 -c "damage > 100"
ursamu debug interactive

# 8. Profile performance
ursamu profile start combat-system.mud --memory --cpu
ursamu profile stop -r
ursamu profile report -f html -o performance.html

# 9. Build and deploy
ursamu project build --minify --sourcemap
ursamu project deploy -e staging --backup
ursamu project deploy -e production --dry-run
```

### Debugging Session Example

```bash
# Start debugging session
ursamu debug start combat.mud --entry

# Set conditional breakpoints
ursamu debug break 15 -c "player.health < 20"
ursamu debug break 30 -c "enemy.type === 'boss'"

# Step through execution
ursamu debug continue    # Hit first breakpoint
ursamu debug vars       # Check variables
ursamu debug eval "player.health = 100"  # Modify state
ursamu debug next       # Step over
ursamu debug stack -v   # Check call stack

# Watch variables
ursamu debug watch player.experience
ursamu debug continue

# Interactive debugging
ursamu debug interactive
```

### Performance Analysis Example

```bash
# Start comprehensive profiling
ursamu profile start intensive-script.mud --memory --cpu --functions --heap -d 120000

# Let script run, then stop and analyze
ursamu profile stop -r

# Generate detailed reports
ursamu profile report -f html -o detailed-analysis.html --top 50
ursamu profile memory intensive-script.mud --gc --leaks
ursamu profile trace intensive-script.mud --filter "process*" --depth 15

# Compare with baseline
ursamu profile benchmark intensive-script.mud --save baseline-v1
# After optimizations...
ursamu profile benchmark intensive-script.mud --compare baseline-v1
```

---

## Tips & Best Practices

### Script Development
- Always validate scripts before deployment: `ursamu script validate --strict --deps`
- Use hot-reload during development: `ursamu script watch`
- Test scripts with realistic data: `ursamu script test -i '{...realistic-data...}'`
- Version your scripts in git and use meaningful commit messages

### Debugging
- Set conditional breakpoints to avoid stopping on every iteration
- Use `debug eval` to test fixes before modifying code
- Watch key variables to understand state changes
- Save debugging sessions for complex issues: use `debug history`

### Performance
- Profile regularly, not just when problems occur
- Use memory profiling for long-running scripts
- Compare performance after each optimization
- Set up automated benchmarking for critical scripts

### Project Management
- Initialize projects with git: `ursamu project init --git`
- Use project templates for consistency
- Run health checks regularly: `ursamu project health`
- Create backups before major deployments
- Use staging environments: `ursamu project deploy -e staging`

### Configuration
- Set up project-specific configurations for team consistency
- Use verbose mode for troubleshooting: `-v` or `--verbose`
- Customize editor integration: `ursamu project config editor "code --wait"`
- Configure reasonable timeouts for your environment

### Error Handling
- Always check command exit codes in scripts
- Use `--dry-run` options when available for safe testing
- Enable verbose logging for debugging configuration issues
- Keep backup configurations for quick recovery

---

## Getting Help

- Use `--help` with any command for detailed information
- Check the [main documentation](README.md) for architectural details
- Report issues on [GitHub](https://github.com/lcanady/mud/issues)
- Use verbose mode (`-v`) for troubleshooting

**Example help commands:**
```bash
ursamu --help                    # Main CLI help
ursamu script --help            # Script command help
ursamu debug break --help       # Specific subcommand help
```

---

*This CLI reference covers all available commands and options. For the latest updates and additional examples, check the official documentation and GitHub repository.*