# TraceRTM CLI Tutorial

**Version**: 1.0  
**Last Updated**: 2025-01-27

---

## 📖 Welcome

This tutorial will guide you through using TraceRTM CLI to manage your projects. By the end, you'll be able to create items, manage links, switch views, and use all core features.

**Estimated Time**: 30-45 minutes

---

## Tutorial 1: Your First Project

### Step 1: Initialize Configuration

First, set up TraceRTM:

```bash
# Initialize with SQLite (easiest for getting started)
rtm config init --database-url sqlite:///tracertm.db
```

**Expected Output**:
```
✓ Configuration initialized successfully
Config file: ~/.tracertm/config.json
```

### Step 2: Create Your First Project

```bash
# Create a project
rtm project init "My First Project" \
  --description "Learning TraceRTM"
```

**Expected Output**:
```
✓ Project 'My First Project' initialized successfully!
Database: sqlite:///tracertm.db
Project ID: <project-id>
```

### Step 3: Verify Setup

```bash
# Check database status
rtm db status

# List projects
rtm project list
```

**Congratulations!** You've set up your first TraceRTM project.

---

## Tutorial 2: Creating Items

### Step 1: Create a Feature

```bash
# Create an epic
rtm item create "User Management System" \
  --view FEATURE \
  --type epic \
  --description "Complete user management functionality"
```

**Note the ID** from the output (e.g., `abc123...`)

### Step 2: Create a Feature Under the Epic

```bash
# Create a feature (replace <epic-id> with actual ID)
rtm item create "User Authentication" \
  --view FEATURE \
  --type feature \
  --parent <epic-id> \
  --description "Login and registration features"
```

### Step 3: Create a Story

```bash
# Create a user story
rtm item create "User can login with email" \
  --view FEATURE \
  --type story \
  --parent <feature-id> \
  --status todo
```

### Step 4: List Your Items

```bash
# List all items
rtm item list

# List only feature view items
rtm item list --view FEATURE

# List only todo items
rtm item list --status todo
```

### Step 5: View Item Details

```bash
# Show item details (use partial ID)
rtm item show <item-id>

# Show with metadata
rtm item show <item-id> --metadata
```

**You've created your first item hierarchy!**

---

## Tutorial 3: Managing Links

### Step 1: Create Items in Different Views

```bash
# Create a feature
FEATURE_ID=$(rtm item create "Login Feature" \
  --view FEATURE --type feature | grep "ID:" | awk '{print $2}')

# Create a code file
CODE_ID=$(rtm item create "auth/login.py" \
  --view CODE --type file | grep "ID:" | awk '{print $2}')

# Create a test
TEST_ID=$(rtm item create "test_login.py" \
  --view TEST --type test_case | grep "ID:" | awk '{print $2}')
```

### Step 2: Create Links

```bash
# Link feature to code (implements)
rtm link create \
  --source $FEATURE_ID \
  --target $CODE_ID \
  --type implements

# Link feature to test (tested_by)
rtm link create \
  --source $FEATURE_ID \
  --target $TEST_ID \
  --type tested_by

# Link code to test (tested_by)
rtm link create \
  --source $CODE_ID \
  --target $TEST_ID \
  --type tested_by
```

### Step 3: List Links

```bash
# List all links
rtm link list

# List links from feature
rtm link list --source $FEATURE_ID

# List links to code
rtm link list --target $CODE_ID
```

**You've created cross-view traceability!**

---

## Tutorial 4: View Switching

### Step 1: List Available Views

```bash
# See all available views
rtm view list
```

### Step 2: Switch Between Views

```bash
# Switch to feature view
rtm view switch FEATURE
rtm item list

# Switch to code view
rtm view switch CODE
rtm item list

# Switch to test view
rtm view switch TEST
rtm item list
```

### Step 3: View Statistics

```bash
# Show statistics for all views
rtm view stats

# Show statistics for specific view
rtm view stats --view FEATURE
```

### Step 4: Check Current View

```bash
# See which view you're in
rtm view current
```

**You can now navigate between different project perspectives!**

---

## Tutorial 5: Advanced Operations

### Step 1: Update Items

```bash
# Update item status
rtm item update <item-id> --status in_progress

# Update multiple fields
rtm item update <item-id> \
  --title "Updated Title" \
  --description "Updated description" \
  --status done
```

### Step 2: Bulk Operations

```bash
# Update all todo items in FEATURE view to in_progress
rtm item bulk-update \
  --view FEATURE \
  --status todo \
  --new-status in_progress \
  --force
```

### Step 3: Delete Items

```bash
# Delete an item (with confirmation)
rtm item delete <item-id>

# Delete without confirmation
rtm item delete <item-id> --force
```

### Step 4: Backup Your Work

```bash
# Create a backup
rtm backup backup --output my_backup.json.gz

# Restore from backup (if needed)
rtm backup restore my_backup.json.gz --force
```

**You've mastered the core operations!**

---

## Tutorial 6: Querying Items

### Step 1: Basic Queries

```bash
# Query by status
rtm query --filter status=todo

# Query by view
rtm query --view FEATURE

# Query with multiple filters
rtm query --filter status=todo,view=FEATURE
```

### Step 2: Query by Relationship

```bash
# Find items related to a specific item
rtm query --related-to ITEM-001

# Filter by link type
rtm query --related-to ITEM-001 --link-type tests
```

### Step 3: Cross-Project Queries

```bash
# Query across all projects
rtm query --all-projects --status todo

# JSON output for scripting
rtm query --filter status=todo --json
```

**You can now query items efficiently!**

---

## Tutorial 7: Saved Queries

### Step 1: Save a Query

```bash
# Save a frequently-used query
rtm saved-queries save "my-todos" --filter status=todo

# Save with multiple filters
rtm saved-queries save "high-priority-features" \
  --priority high --view FEATURE
```

### Step 2: List Saved Queries

```bash
# See all saved queries
rtm saved-queries list
```

### Step 3: Run a Saved Query

```bash
# Run a saved query
rtm saved-queries run "my-todos"
```

### Step 4: Delete a Saved Query

```bash
# Remove a saved query
rtm saved-queries delete "my-todos"
```

**You can now reuse complex queries easily!**

---

## Tutorial 8: Progress Tracking

### Step 1: View Overall Progress

```bash
# Show project-wide progress
rtm progress show

# Show progress for a specific view
rtm progress show --view FEATURE

# Show progress for a specific item
rtm progress show --item ITEM-001
```

### Step 2: Identify Blocked Items

```bash
# Find items that are blocking others
rtm progress blocked
```

### Step 3: Find Stalled Items

```bash
# Find items with no recent updates
rtm progress stalled

# Customize threshold
rtm progress stalled --days 14
```

### Step 4: Track Velocity

```bash
# Show completion velocity
rtm progress velocity

# Show velocity for last 30 days
rtm progress velocity --days 30
```

### Step 5: Generate Progress Report

```bash
# Generate report for last 30 days
rtm progress report

# Generate JSON report
rtm progress report --days 30 --json
```

**You can now track project progress effectively!**

---

## Tutorial 9: History & Rollback

### Step 1: View Item History

```bash
# Show history for an item
rtm history ITEM-001

# Show more history entries
rtm history ITEM-001 --limit 50
```

### Step 2: Query State at Specific Date

```bash
# See item state at a specific date
rtm history ITEM-001 --at "2025-01-15"

# Use ISO datetime format
rtm history ITEM-001 --at "2025-01-15T10:30:00"
```

### Step 3: View Version Information

```bash
# Show current version
rtm history version ITEM-001

# Show specific version
rtm history version ITEM-001 --version 3
```

### Step 4: Rollback to Previous Version

```bash
# Rollback to version 3 (with confirmation)
rtm history rollback ITEM-001 --version 3

# Rollback without confirmation
rtm history rollback ITEM-001 --version 2 --confirm
```

**You can now track changes and recover from mistakes!**

---

## Tutorial 10: Importing Data

### Step 1: Import from JSON

```bash
# Import items from JSON file
rtm import json backup.json

# Import to specific project
rtm import json backup.json --project my-project

# Validate before importing
rtm import json backup.json --validate-only
```

### Step 2: Import from YAML

```bash
# Import from YAML file
rtm import yaml backup.yaml --project my-project
```

### Step 3: Import from Jira

```bash
# Import from Jira export
rtm import jira jira-export.json --project imported-project

# Validate Jira format
rtm import jira jira-export.json --validate-only
```

### Step 4: Import from GitHub

```bash
# Import from GitHub Projects export
rtm import github github-export.json --project imported-project
```

**You can now migrate data from other tools!**

---

## Tutorial 11: Multi-Project Management

### Step 1: View All Projects

```bash
# Show dashboard of all projects
rtm dashboard
```

### Step 2: Cross-Project Queries

```bash
# Query items across all projects
rtm query --all-projects --status todo

# Export all projects
rtm project export --all-projects --output all-projects.json
```

**You can now manage multiple projects efficiently!**

---

## Tutorial 12: Advanced Search

### Step 1: Basic Search

```bash
# Search by text
rtm search "authentication"
```

### Step 2: Search with Filters

```bash
# Search with view filter
rtm search "login" --view FEATURE

# Search with status filter
rtm search "user" --status todo

# Combine multiple filters
rtm search "feature" --view FEATURE --status blocked --owner agent-12
```

### Step 3: Date Range Filters

```bash
# Search items created after date
rtm search "test" --created-after "2025-01-01"

# Search items updated in date range
rtm search "bug" --updated-after "2025-01-01" --updated-before "2025-01-31"
```

### Step 4: Fuzzy Matching

```bash
# Enable fuzzy matching for typos
rtm search "auth" --fuzzy
```

**You can now find items quickly with powerful search!**

---

## Next Steps

### Explore More Features

- **Link Management**: `rtm link detect-cycles`, `rtm link auto-link`
- **Multi-Project**: `rtm dashboard`, `rtm query --all-projects`
- **Advanced Search**: `rtm search` with all filters
- **Progress Tracking**: `rtm progress` commands
- **History**: `rtm history` with temporal queries

### Learn More

- **CLI User Guide**: Complete command reference
- **CLI API Reference**: Detailed API documentation
- **CLI Examples**: More advanced examples

### Get Help

```bash
# Get help for any command
rtm --help
rtm item --help
rtm item create --help
```

---

**Congratulations!** You've completed the TraceRTM CLI tutorial. You're ready to manage your projects with TraceRTM.

---

**Last Updated**: 2025-01-27  
**Version**: 1.0
