---
title: "CLI Commands Reference"
description: "Comprehensive reference for all TraceRTM CLI commands"
---

# CLI Commands Reference

This page provides a comprehensive reference for all TraceRTM CLI commands, organized by functional groups.

## Quick Reference

| Command Group | Purpose |
|--------------|---------|
| [`rtm item`](#item-commands) | Item management (create, list, update, delete) |
| [`rtm project`](#project-commands) | Project management and initialization |
| [`rtm link`](#link-commands) | Traceability link management |
| [`rtm search`](#search-commands) | Full-text search across items |
| [`rtm query`](#query-commands) | Structured queries with filters |
| [`rtm sync`](#sync-commands) | Offline-first synchronization |
| [`rtm export`](#export-commands) | Export data to various formats |
| [`rtm import`](#import-commands) | Import from JSON, YAML, Jira, GitHub |
| [`rtm agents`](#agent-commands) | Agent monitoring and metrics |
| [`rtm progress`](#progress-commands) | Progress tracking and velocity |
| [`rtm history`](#history-commands) | Version history and rollback |
| [`rtm design`](#design-commands) | Design system integration |
| [`rtm benchmark`](#benchmark-commands) | Performance benchmarking |

---

## Item Commands

Manage items across all views (FEATURE, CODE, WIREFRAME, API, TEST, DATABASE, ROADMAP, PROGRESS).

### `rtm item create`

Create a new item in a specific view.

**Syntax:**
```bash
rtm item create <title> --view <VIEW> --type <TYPE> [OPTIONS]
```

**Options:**
- `--view, -v` (required): View (FEATURE, CODE, WIREFRAME, API, TEST, DATABASE, ROADMAP, PROGRESS)
- `--type, -t` (required): Item type (epic, feature, story, task, bug, etc.)
- `--description, -d`: Item description
- `--status, -s`: Status (default: todo)
- `--priority`: Priority (low, medium, high) (default: medium)
- `--owner, -o`: Item owner
- `--parent, -p`: Parent item ID
- `--metadata, -m`: Metadata as JSON
- `--local`: Force local-only operation (no sync)
- `--project`: Project directory path

**Examples:**
```bash
# Create a feature epic
rtm item create "User Authentication" --view FEATURE --type epic

# Create with description and owner
rtm item create "Login API" --view API --type endpoint \
  --description "REST endpoint for user login" --owner alice

# Create with metadata
rtm item create "Test Suite" --view TEST --type test_suite \
  --metadata '{"framework": "pytest", "coverage": 85}'

# Create in specific project
rtm item create "New Feature" --view FEATURE --type feature \
  --project /path/to/project
```

**Expected Output:**
```
✓ Created EPIC-001: User Authentication
  File: .trace/epics/EPIC-001.md
  Project: my-project
  Indexed: /Users/user/.tracertm/tracertm.db
  Queued for sync to remote
```

---

### `rtm item list`

List items with filters.

**Syntax:**
```bash
rtm item list [OPTIONS]
```

**Options:**
- `--view, -v`: Filter by view
- `--type, -t`: Filter by type
- `--status, -s`: Filter by status
- `--priority`: Filter by priority
- `--owner, -o`: Filter by owner
- `--limit, -l`: Maximum items to show (default: 50)
- `--deleted`: Include deleted items
- `--json`: Output as JSON
- `--project`: Project directory path

**Examples:**
```bash
# List all items
rtm item list

# List by status and view
rtm item list --status todo --view FEATURE

# List with JSON output
rtm item list --type epic --json

# Limit results
rtm item list --limit 10
```

**Expected Output:**
```
Items in my-project (15)
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃ External ID┃ Title                    ┃ Type    ┃ Status  ┃ Priority┃ Owner   ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ EPIC-001   │ User Authentication      │ epic    │ todo    │ high    │ alice   │
│ STORY-001  │ Login Form              │ story   │ in_prog │ medium  │ bob     │
└────────────┴──────────────────────────┴─────────┴─────────┴─────────┴─────────┘
```

---

### `rtm item show`

Show detailed information about an item.

**Syntax:**
```bash
rtm item show <ITEM_ID> [OPTIONS]
```

**Options:**
- `--metadata, -m`: Show metadata
- `--view, -v`: Show in specific view context
- `--depth, -d`: Drill-down depth (show children) (default: 1)
- `--version`: Show specific version
- `--children, -c`: Show all children
- `--tree, -t`: Show hierarchy tree (ASCII)
- `--ancestors, -a`: Show ancestor path

**Examples:**
```bash
# Basic item details
rtm item show EPIC-001

# Show with metadata
rtm item show EPIC-001 --metadata

# Show hierarchy tree
rtm item show EPIC-001 --tree

# Show ancestor path
rtm item show STORY-001 --ancestors
```

**Expected Output:**
```
Item: User Authentication
ID: abc12345
View: FEATURE
Type: epic
Status: todo
Priority: high
Owner: alice
Version: 3

Description:
Implement comprehensive user authentication system with OAuth2 support.

Path:
  Project Root > Features > User Authentication

Children (3):
  • Login Form (def45678) - in_progress
  • Password Reset (ghi78901) - todo
  • OAuth Integration (jkl01234) - blocked

Links (2):
  → implements → Login API (mno34567)
  → tests → Auth Test Suite (pqr67890)

Created: 2025-01-15 10:30:00
Updated: 2025-01-20 14:45:30
```

---

### `rtm item update`

Update an existing item.

**Syntax:**
```bash
rtm item update <ITEM_ID> [OPTIONS]
```

**Options:**
- `--title`: New title
- `--description, -d`: New description
- `--status, -s`: New status
- `--priority`: New priority
- `--owner, -o`: New owner
- `--metadata, -m`: Metadata as JSON
- `--local`: Force local-only operation
- `--project`: Project directory path

**Examples:**
```bash
# Update status
rtm item update EPIC-001 --status in_progress

# Update multiple fields
rtm item update EPIC-001 --title "Enhanced Auth" \
  --priority high --owner alice

# Update metadata
rtm item update EPIC-001 --metadata '{"sprint": 5, "points": 13}'
```

**Expected Output:**
```
✓ Updated EPIC-001: Enhanced Auth
  Version: 4
  Markdown updated in .trace/epics/EPIC-001.md
  Queued for sync to remote
```

---

### `rtm item delete`

Delete an item (soft delete by default).

**Syntax:**
```bash
rtm item delete <ITEM_ID> [OPTIONS]
```

**Options:**
- `--force, -f`: Force delete without confirmation
- `--local`: Force local-only operation
- `--project`: Project directory path

**Examples:**
```bash
# Delete with confirmation
rtm item delete EPIC-001

# Force delete
rtm item delete EPIC-001 --force
```

**Expected Output:**
```
✓ Deleted EPIC-001
  Markdown file removed: .trace/epics/EPIC-001.md
  SQLite index updated
  Queued for sync to remote
```

---

### `rtm item bulk-create`

Bulk create items from CSV file.

**Syntax:**
```bash
rtm item bulk-create --input <FILE> [OPTIONS]
```

**CSV Format:**
- Required columns: Title, View, Type
- Optional columns: Description, Status, Priority, Owner, Parent ID, Metadata (JSON)

**Options:**
- `--input, -i` (required): CSV file path
- `--skip-preview`: Skip preview and execute directly

**Examples:**
```bash
# Bulk create with preview
rtm item bulk-create --input items.csv

# Skip preview for automation
rtm item bulk-create --input items.csv --skip-preview
```

**Expected Output:**
```
Bulk Create Preview
  Total items to create: 25

Sample items (first 5):
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ Row ┃ Title              ┃ View   ┃ Type   ┃ Status ┃ Owner  ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
│ 2   │ User Login        │ FEATURE│ story  │ todo   │ alice  │
│ 3   │ Password Reset    │ FEATURE│ story  │ todo   │ bob    │
└─────┴───────────────────┴────────┴────────┴────────┴────────┘

  Estimated duration: 2.50s

Proceed with bulk create? [y/N]: y

✓ Created 25 items
```

---

### `rtm item bulk-update`

Bulk update multiple items.

**Syntax:**
```bash
rtm item bulk-update [OPTIONS]
```

**Options:**
- `--view, -v`: Filter by view
- `--status, -s`: Filter by current status
- `--new-status`: New status to set
- `--new-priority`: New priority to set
- `--new-owner`: New owner to set
- `--skip-preview`: Skip preview
- `--force, -f`: Force update without confirmation (deprecated)

**Examples:**
```bash
# Update status for all todo items in FEATURE view
rtm item bulk-update --view FEATURE --status todo --new-status in_progress

# Update priority
rtm item bulk-update --status blocked --new-priority high

# Skip preview for automation
rtm item bulk-update --status done --new-status archived --skip-preview
```

**Expected Output:**
```
Bulk Update Preview
  Total items: 12

Sample items (first 5):
┏━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ ID     ┃ Title          ┃ Current      ┃ New            ┃
┡━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ abc123 │ User Login     │ status=todo  │ status=in_prog │
│ def456 │ Password Reset │ status=todo  │ status=in_prog │
└────────┴────────────────┴──────────────┴────────────────┘

  Estimated duration: 1.20s

Proceed with bulk update? [y/N]: y

✓ Updated 12 items
```

---

## Project Commands

Manage TraceRTM projects with local .trace/ directories and global database indexing.

### `rtm project init`

Initialize a new TraceRTM project.

**Syntax:**
```bash
rtm project init <NAME> [OPTIONS]
```

**Options:**
- `--description, -d`: Project description
- `--database-url`: Database URL (default: SQLite)

**Examples:**
```bash
# Initialize basic project
rtm project init my-project

# With description
rtm project init my-project --description "User management system"
```

**Expected Output:**
```
✓ Project 'my-project' initialized successfully!
Database: /Users/user/.tracertm/tracertm.db
Project directory: /Users/user/.tracertm/projects/my-project
Project ID: abc12345

Directory structure created:
  ├─ epics/
  ├─ stories/
  ├─ tests/
  ├─ tasks/
  ├─ .meta/
  └─ README.md
```

---

### `rtm project list`

List all projects.

**Syntax:**
```bash
rtm project list [OPTIONS]
```

**Options:**
- `--sync-status`: Show sync status
- `--paths/--no-paths`: Show local .trace/ paths (default: true)

**Examples:**
```bash
# List all projects
rtm project list

# Show sync status
rtm project list --sync-status
```

**Expected Output:**
```
Projects
┏━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━┓
┃ ID      ┃ Name         ┃ Description        ┃ Items ┃ Last Indexed ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━┩
│ abc12345│ my-project   │ User management... │ 42    │ 2025-01-20   │
│ def67890│ api-service  │ REST API service   │ 18    │ 2025-01-19   │
└─────────┴──────────────┴────────────────────┴───────┴──────────────┘

Current project: my-project
Global database: /Users/user/.tracertm/tracertm.db
```

---

### `rtm project switch`

Switch to a different project (completes in <500ms).

**Syntax:**
```bash
rtm project switch <NAME>
```

**Examples:**
```bash
rtm project switch api-service
```

**Expected Output:**
```
✓ Switched to project 'api-service' (245ms)
Local directory: /Users/user/.tracertm/projects/api-service
```

---

### `rtm project export`

Export entire project for backup/sharing.

**Syntax:**
```bash
rtm project export <NAME> --output <FILE> [OPTIONS]
```

**Options:**
- `--output, -o` (required): Output file path
- `--format, -f`: Export format (json, yaml) (default: json)
- `--include-markdown`: Include markdown files in export

**Examples:**
```bash
# Export to JSON
rtm project export my-project --output backup.json

# Export to YAML with markdown
rtm project export my-project --output backup.yaml \
  --format yaml --include-markdown
```

**Expected Output:**
```
✓ Exported project 'my-project' to backup.json
  Format: json
  Size: 524288 bytes
✓ Markdown files archived to backup.tar.gz
```

---

### `rtm project clone`

Clone a project.

**Syntax:**
```bash
rtm project clone <SOURCE> <TARGET> [OPTIONS]
```

**Options:**
- `--items/--no-items`: Include items (default: true)
- `--links/--no-links`: Include links (default: true)
- `--markdown/--no-markdown`: Clone markdown files (default: true)

**Examples:**
```bash
# Full clone
rtm project clone my-project new-project

# Clone structure only (no items)
rtm project clone template-project new-project --no-items

# Clone without markdown
rtm project clone my-project new-project --no-markdown
```

---

## Link Commands

Manage traceability links between items across views.

### `rtm link create`

Create a traceability link.

**Syntax:**
```bash
rtm link create <SOURCE_ID> <TARGET_ID> --type <TYPE> [OPTIONS]
```

**Link Types:**
- `implements` - Code implements requirement
- `tests` - Test verifies requirement
- `designs` - Design represents requirement
- `depends_on` - Depends on another item
- `blocks` - Blocks another item
- `related_to` - General relationship
- `decomposes_to` - Parent decomposes to child

**Options:**
- `--type, -t` (required): Link type
- `--metadata, -m`: Metadata as JSON

**Examples:**
```bash
# Create implementation link
rtm link create STORY-001 CODE-001 --type implements

# Create test link
rtm link create STORY-001 TEST-001 --type tests

# Create dependency
rtm link create TASK-001 TASK-002 --type depends_on

# With metadata
rtm link create STORY-001 DESIGN-001 --type designs \
  --metadata '{"figma_url": "https://..."}'
```

**Expected Output:**
```
✓ Created link: User Login --[implements]--> LoginComponent
  Link ID: xyz789
```

---

### `rtm link list`

List all links in the project.

**Syntax:**
```bash
rtm link list [OPTIONS]
```

**Options:**
- `--item, -i`: Filter by item ID
- `--type, -t`: Filter by link type
- `--limit, -l`: Maximum links to show (default: 50)

**Examples:**
```bash
# List all links
rtm link list

# List links for specific item
rtm link list --item STORY-001

# List by type
rtm link list --type implements
```

---

### `rtm link show`

Show all links for a specific item.

**Syntax:**
```bash
rtm link show <ITEM_ID> [OPTIONS]
```

**Options:**
- `--view, -v`: Filter by target view

**Examples:**
```bash
# Show all links
rtm link show STORY-001

# Filter by view
rtm link show STORY-001 --view CODE
```

**Expected Output:**
```
Links for: User Login
Item ID: abc123, View: FEATURE

Outgoing Links:
  → [implements] → LoginComponent (def456) [CODE]
  → [tests] → LoginTests (ghi789) [TEST]

Incoming Links:
  ← [decomposes_to] ← User Authentication (jkl012) [FEATURE]
```

---

### `rtm link detect-cycles`

Detect cycles in dependency graph.

**Syntax:**
```bash
rtm link detect-cycles [OPTIONS]
```

**Options:**
- `--type, -t`: Link type to check (default: depends_on)

**Examples:**
```bash
rtm link detect-cycles
rtm link detect-cycles --type depends_on
```

**Expected Output:**
```
✗ Found 2 cycle(s) in depends_on relationships

Cycles detected:

  Cycle 1:
    Task A (abc123) →
    Task B (def456) →
    Task C (ghi789) →
    Task A (abc123)

  Cycle 2:
    Feature X (jkl012) →
    Feature Y (mno345) →
    Feature X (jkl012)
```

---

### `rtm link impact`

Analyze impact of changing an item.

**Syntax:**
```bash
rtm link impact <ITEM_ID> [OPTIONS]
```

**Options:**
- `--depth, -d`: Maximum depth to traverse (default: 10)
- `--type, -t`: Link type to follow (default: depends_on)

**Examples:**
```bash
# Basic impact analysis
rtm link impact STORY-001

# Custom depth and link type
rtm link impact STORY-001 --depth 5 --type implements
```

**Expected Output:**
```
Impact Analysis for: User Login
Item ID: abc123

Total Affected Items: 8
Max Depth Reached: 3

Affected by Depth:
  Depth 1: 3 items
  Depth 2: 4 items
  Depth 3: 1 items

Affected by View:
  CODE: 4 items
  TEST: 3 items
  API: 1 items

Affected Items (showing first 8):
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ Depth ┃ Item ID ┃ Title            ┃ View  ┃ Type   ┃ Status ┃
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
│ 1     │ def456  │ LoginComponent   │ CODE  │ file   │ done   │
│ 1     │ ghi789  │ LoginTests       │ TEST  │ test   │ todo   │
│ 2     │ jkl012  │ AuthService      │ CODE  │ class  │ in_pr  │
└───────┴─────────┴──────────────────┴───────┴────────┴────────┘
```

---

### `rtm link graph`

Visualize item relationships as ASCII tree.

**Syntax:**
```bash
rtm link graph <ITEM_ID> [OPTIONS]
```

**Options:**
- `--depth, -d`: Maximum depth to traverse (default: 2)
- `--type, -t`: Filter by link type

**Examples:**
```bash
rtm link graph EPIC-001
rtm link graph EPIC-001 --depth 3 --type implements
```

**Expected Output:**
```
Traceability Graph
Root: abc123, Max Depth: 2, Link Type: all

User Authentication (abc123) [FEATURE]
    ├─[implements]
    └── LoginComponent (def456) [CODE]
        ├─[tests]
        └── LoginTests (ghi789) [TEST]
    ├─[implements]
    └── AuthService (jkl012) [CODE]
```

---

### `rtm link matrix`

Show traceability matrix in table format.

**Syntax:**
```bash
rtm link matrix [OPTIONS]
```

**Options:**
- `--type, -t`: Filter by link type
- `--view, -v`: Filter by view

**Examples:**
```bash
rtm link matrix
rtm link matrix --type implements
rtm link matrix --view FEATURE
```

**Expected Output:**
```
Traceability Matrix (42 links)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ Source          ┃ Source ID┃ View   ┃ Link Type  ┃ Target          ┃ Target ID┃ View   ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ User Login      │ abc123   │ FEATURE│ implements │ LoginComponent  │ def456   │ CODE   │
│ User Login      │ abc123   │ FEATURE│ tests      │ LoginTests      │ ghi789   │ TEST   │
└─────────────────┴──────────┴────────┴────────────┴─────────────────┴──────────┴────────┘

Summary:
  Total Links: 42
  By Type:
    implements: 18
    tests: 15
    depends_on: 6
    designs: 3
```

---

## Search Commands

Full-text search across all items with advanced filtering.

### `rtm search`

Search items by title, description, and metadata.

**Syntax:**
```bash
rtm search <QUERY> [OPTIONS]
```

**Options:**
- `--view, -v`: Filter by view
- `--status, -s`: Filter by status
- `--type, -t`: Filter by type
- `--owner, -o`: Filter by owner
- `--created-after`: Filter by creation date
- `--created-before`: Filter by creation date
- `--updated-after`: Filter by update date
- `--updated-before`: Filter by update date
- `--fuzzy`: Enable fuzzy matching
- `--limit, -l`: Maximum results (default: 50)

**Examples:**
```bash
# Basic search
rtm search "authentication"

# Search with filters
rtm search "login" --view FEATURE --status todo

# Search by owner and type
rtm search "user" --owner alice --type feature

# Date-based search
rtm search "test" --created-after "2025-01-01"

# Fuzzy search
rtm search "auth" --fuzzy

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

**Expected Output:**
```
Search Results: 'authentication' (8)
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
┃ ID      ┃ Title                  ┃ View   ┃ Type   ┃ Status ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
│ abc123  │ User Authentication    │ FEATURE│ epic   │ todo   │
│ def456  │ Authentication Service │ CODE   │ class  │ in_pr  │
└─────────┴────────────────────────┴────────┴────────┴────────┘
```

---

## Query Commands

Structured queries with filter criteria and relationship support.

### `rtm query`

Query items with structured filters.

**Syntax:**
```bash
rtm query [OPTIONS]
```

**Options:**
- `--filter, -f`: Filter criteria (e.g., status=todo,view=FEATURE)
- `--view, -v`: Filter by view
- `--status, -s`: Filter by status
- `--priority`: Filter by priority
- `--owner, -o`: Filter by owner
- `--type, -t`: Filter by item type
- `--related-to`: Query items related to item ID
- `--link-type`: Filter by link type (with --related-to)
- `--all-projects`: Query across all projects
- `--limit, -l`: Maximum results (default: 50)
- `--json`: Output as JSON

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

# Multiple criteria
rtm query --filter status=todo,view=FEATURE

# Using flags
rtm query --status in_progress --view CODE

# Query by relationship
rtm query --related-to ITEM-001 --link-type tests

# Cross-project query
rtm query --all-projects --status todo

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

**Expected Output:**
```
Query Results (12)
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ ID      ┃ Title          ┃ View   ┃ Type   ┃ Status ┃ Priority┃ Owner ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ abc123  │ User Login     │ FEATURE│ story  │ todo   │ high   │ alice │
│ def456  │ Password Reset │ FEATURE│ story  │ todo   │ medium │ bob   │
└─────────┴────────────────┴────────┴────────┴────────┴────────┴───────┘
```

---

## Sync Commands

Offline-first synchronization between local and remote.

### `rtm sync`

Run full bidirectional sync.

**Syntax:**
```bash
rtm sync [OPTIONS]
```

**Options:**
- `--force, -f`: Force sync even if recently synced
- `--dry-run`: Show what would be synced

**Examples:**
```bash
# Normal sync
rtm sync

# Force sync
rtm sync --force

# Preview changes
rtm sync --dry-run
```

**Expected Output:**
```
✓ Sync completed successfully

Entities synced: 15
Duration: 2.3s
Conflicts: 0
Errors: 0
```

---

### `rtm sync status`

Show current sync status.

**Syntax:**
```bash
rtm sync status
```

**Expected Output:**
```
┌─────────────────────────────────────┐
│          Sync Status                │
├─────────────────────────────────────┤
│ Status:          Up to date         │
│ Online:          Online             │
│ Last sync:       2m ago             │
│ Pending changes: 0                  │
└─────────────────────────────────────┘
```

---

### `rtm sync push`

Upload local changes only.

**Syntax:**
```bash
rtm sync push [OPTIONS]
```

**Options:**
- `--force, -f`: Force push even if conflicts exist

**Examples:**
```bash
rtm sync push
rtm sync push --force
```

---

### `rtm sync pull`

Download remote changes only.

**Syntax:**
```bash
rtm sync pull [OPTIONS]
```

**Options:**
- `--since`: Download changes since timestamp (ISO format)

**Examples:**
```bash
rtm sync pull
rtm sync pull --since "2025-01-15T10:30:00"
```

---

### `rtm sync conflicts`

List unresolved sync conflicts.

**Syntax:**
```bash
rtm sync conflicts [OPTIONS]
```

**Options:**
- `--type, -t`: Filter by entity type

**Examples:**
```bash
rtm sync conflicts
rtm sync conflicts --type item
```

**Expected Output:**
```
Found 3 unresolved conflicts:

Unresolved Conflicts
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ ID          ┃ Entity         ┃ Type ┃ Local V ┃ Remote V ┃ Detected    ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ conflict... │ abc123456789...│ item │ 5       │ 6        │ 2025-01-20  │
└─────────────┴────────────────┴──────┴─────────┴──────────┴─────────────┘

Run 'rtm sync resolve <conflict_id>' to resolve a conflict
Or 'rtm sync' with a conflict strategy to auto-resolve all
```

---

### `rtm sync resolve`

Resolve a specific conflict.

**Syntax:**
```bash
rtm sync resolve <CONFLICT_ID> [OPTIONS]
```

**Strategies:**
- `last_write_wins`: Use newest timestamp (default)
- `local_wins`: Always prefer local version
- `remote_wins`: Always prefer remote version
- `manual`: Provide merged data with --data

**Options:**
- `--strategy, -s`: Resolution strategy (default: last_write_wins)
- `--data`: Merged data as JSON (for manual strategy)

**Examples:**
```bash
# Automatic resolution
rtm sync resolve conflict_abc123

# Use local version
rtm sync resolve conflict_abc123 --strategy local_wins

# Manual merge
rtm sync resolve conflict_abc123 --strategy manual \
  --data '{"title": "Merged Title", "status": "in_progress"}'
```

---

## Export Commands

Export project data to various formats.

### `rtm export`

Export project data.

**Syntax:**
```bash
rtm export [OPTIONS]
```

**Options:**
- `--format, -f`: Export format (json, yaml, csv, markdown) (default: json)
- `--output, -o`: Output file path

**Examples:**
```bash
# Export to JSON
rtm export --format json --output data.json

# Export to YAML
rtm export --format yaml --output data.yaml

# Export to CSV
rtm export --format csv --output items.csv

# Export to Markdown
rtm export --format markdown --output docs.md

# Output to stdout
rtm export --format json
```

**Expected Output:**
```
✓ Exported to data.json
  Format: json
  Size: 524288 bytes
```

---

## Import Commands

Import data from various sources.

### `rtm import json`

Import from JSON file.

**Syntax:**
```bash
rtm import json <FILE> [OPTIONS]
```

**Options:**
- `--project, -p`: Target project name
- `--validate-only`: Only validate, don't import

**Examples:**
```bash
rtm import json backup.json
rtm import json backup.json --project my-project
rtm import json backup.json --validate-only
```

---

### `rtm import yaml`

Import from YAML file.

**Syntax:**
```bash
rtm import yaml <FILE> [OPTIONS]
```

**Options:**
- `--project, -p`: Target project name
- `--validate-only`: Only validate, don't import

**Examples:**
```bash
rtm import yaml backup.yaml
rtm import yaml backup.yaml --project my-project
```

---

## Agent Commands

Monitor and manage AI agents.

### `rtm agents list`

List all registered agents.

**Syntax:**
```bash
rtm agents list
```

**Expected Output:**
```
Registered Agents
┏━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Name         ┃ Type     ┃ Status ┃ Last Activity  ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ abc12345 │ Agent-Alpha  │ code     │ active │ 2025-01-20     │
│ def67890 │ Agent-Beta   │ test     │ active │ 2025-01-20     │
└──────────┴──────────────┴──────────┴────────┴────────────────┘
```

---

### `rtm agents activity`

Show agent activity history.

**Syntax:**
```bash
rtm agents activity [OPTIONS]
```

**Options:**
- `--agent, -a`: Filter by agent ID
- `--since`: Time range (e.g., 1h, 24h, 7d)
- `--limit, -l`: Maximum events (default: 50)
- `--json`: Output as JSON

**Examples:**
```bash
rtm agents activity
rtm agents activity --agent agent-001
rtm agents activity --since 1h
rtm agents activity --json
```

---

### `rtm agents metrics`

Show agent performance metrics.

**Syntax:**
```bash
rtm agents metrics [OPTIONS]
```

**Options:**
- `--agent, -a`: Filter by agent ID
- `--since`: Time range (default: 24h)
- `--json`: Output as JSON

**Examples:**
```bash
rtm agents metrics
rtm agents metrics --agent agent-001
rtm agents metrics --since 7d
```

**Expected Output:**
```
Agent Metrics (Last 24h)
┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Agent      ┃ Ops/Hour ┃ Success Rate┃ Conflict Rate┃ Total Ops┃ Conflicts┃
┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ Agent-Alpha│ 12.5     │ 98.5%       │ 1.2%         │ 300     │ 4        │
│ Agent-Beta │ 8.2      │ 99.1%       │ 0.5%         │ 197     │ 1        │
└────────────┴──────────┴─────────────┴──────────────┴─────────┴──────────┘
```

---

### `rtm agents workload`

Show agent workload distribution.

**Syntax:**
```bash
rtm agents workload [OPTIONS]
```

**Options:**
- `--agent, -a`: Filter by agent ID

**Examples:**
```bash
rtm agents workload
rtm agents workload --agent agent-001
```

---

### `rtm agents health`

Check agent health status.

**Syntax:**
```bash
rtm agents health [OPTIONS]
```

**Options:**
- `--agent, -a`: Filter by agent ID

**Examples:**
```bash
rtm agents health
rtm agents health --agent agent-001
```

---

## Progress Commands

Track progress, velocity, and completion metrics.

### `rtm progress show`

Show progress information.

**Syntax:**
```bash
rtm progress show [OPTIONS]
```

**Options:**
- `--item, -i`: Show progress for specific item
- `--view, -v`: Show progress for view

**Examples:**
```bash
# Project progress
rtm progress show

# Item progress
rtm progress show --item EPIC-001

# View progress
rtm progress show --view FEATURE
```

**Expected Output:**
```
Project Progress
  Total Items: 125
  Average Completion: 67.5%
```

---

### `rtm progress blocked`

Show items that are blocking others.

**Syntax:**
```bash
rtm progress blocked [OPTIONS]
```

**Options:**
- `--limit, -l`: Maximum items (default: 50)

**Examples:**
```bash
rtm progress blocked
rtm progress blocked --limit 10
```

---

### `rtm progress stalled`

Show items with no recent progress.

**Syntax:**
```bash
rtm progress stalled [OPTIONS]
```

**Options:**
- `--days, -d`: Days without update (default: 7)
- `--limit, -l`: Maximum items (default: 50)

**Examples:**
```bash
rtm progress stalled
rtm progress stalled --days 14
```

---

### `rtm progress velocity`

Show velocity metrics.

**Syntax:**
```bash
rtm progress velocity [OPTIONS]
```

**Options:**
- `--days, -d`: Time period in days (default: 7)

**Examples:**
```bash
rtm progress velocity
rtm progress velocity --days 30
```

**Expected Output:**
```
Velocity (Last 7 days)

  Items Completed: 18
  Items Created: 22
  Net Change: +4
  Completion Rate: 2.57 items/day
```

---

### `rtm progress report`

Generate progress report.

**Syntax:**
```bash
rtm progress report [OPTIONS]
```

**Options:**
- `--days, -d`: Report period in days (default: 30)
- `--json`: Output as JSON

**Examples:**
```bash
rtm progress report
rtm progress report --days 7
rtm progress report --days 30 --json
```

---

## History Commands

View version history and rollback changes.

### `rtm history`

Show item change history.

**Syntax:**
```bash
rtm history <ITEM_ID> [OPTIONS]
```

**Options:**
- `--limit, -l`: Maximum history entries (default: 20)
- `--at`: Query item state at specific date (temporal query)

**Examples:**
```bash
# Show recent history
rtm history ITEM-001

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

# Temporal query
rtm history ITEM-001 --at "2025-01-15"
rtm history ITEM-001 --at "2025-01-15T10:30:00"
```

**Expected Output:**
```
History for: User Login
Item ID: abc123, Current Version: 5

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Time               ┃ Event        ┃ Agent   ┃ Details            ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ 2025-01-20 14:30   │ item_updated │ alice   │ status: in_progress│
│ 2025-01-18 09:15   │ item_updated │ bob     │ title: User Login  │
│ 2025-01-15 10:30   │ item_created │ system  │ Created: Login     │
└────────────────────┴──────────────┴─────────┴────────────────────┘

Current State:
  Version: 5
  Status: in_progress
  Updated: 2025-01-20 14:30:00
```

---

### `rtm history version`

Show version information.

**Syntax:**
```bash
rtm history version <ITEM_ID> [OPTIONS]
```

**Options:**
- `--version, -v`: Show specific version

**Examples:**
```bash
# Current version
rtm history version ITEM-001

# Specific version
rtm history version ITEM-001 --version 3
```

---

### `rtm history rollback`

Rollback item to previous version.

**Syntax:**
```bash
rtm history rollback <ITEM_ID> --version <VERSION> [OPTIONS]
```

**Options:**
- `--version, -v` (required): Version to rollback to
- `--confirm`: Skip confirmation prompt

**Examples:**
```bash
# Rollback with confirmation
rtm history rollback ITEM-001 --version 3

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

**Expected Output:**
```
✓ Rolled back item to version 3
  Title: User Login
  Status: todo
  New Version: 6
```

---

## Design Commands

Integrate with Storybook and Figma.

### `rtm design init`

Initialize design integration.

**Syntax:**
```bash
rtm design init [OPTIONS]
```

**Examples:**
```bash
rtm design init
```

---

### `rtm design sync`

Sync with Storybook and Figma.

**Syntax:**
```bash
rtm design sync [OPTIONS]
```

**Examples:**
```bash
rtm design sync
```

---

## Benchmark Commands

Performance benchmarking for materialized views.

### `rtm benchmark views`

Benchmark all materialized views.

**Syntax:**
```bash
rtm benchmark views
```

**Expected Output:**
```
Materialized View Performance
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━┓
┃ View           ┃ Query Time ┃ Target ┃ Status ┃ Rows ┃ Size  ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━┩
│ items_by_status│ 45.23ms    │ 100ms  │ ✓      │ 1250 │ 2.5MB │
│ link_counts    │ 32.45ms    │ 100ms  │ ✓      │ 850  │ 1.8MB │
└────────────────┴────────────┴────────┴────────┴──────┴───────┘

Summary: 12/15 views meeting performance targets
```

---

### `rtm benchmark refresh`

Benchmark refresh operations.

**Syntax:**
```bash
rtm benchmark refresh
```

---

### `rtm benchmark report`

Generate comprehensive performance report.

**Syntax:**
```bash
rtm benchmark report
```

---

## Additional Commands

### Shell Completion

Install shell completion for better CLI experience.

**Syntax:**
```bash
rtm item install-completion <SHELL>
```

**Supported Shells:**
- bash
- zsh
- fish

**Examples:**
```bash
rtm item install-completion bash
rtm item install-completion zsh
rtm item install-completion fish --dir ~/.config/zsh/completions
```

---

### Aliases

Manage command aliases.

**Syntax:**
```bash
rtm item list-aliases
rtm item show-alias <ALIAS>
rtm item add-alias <ALIAS> <COMMAND>
rtm item remove-alias <ALIAS>
```

**Examples:**
```bash
# List all aliases
rtm item list-aliases

# Show specific alias
rtm item show-alias i

# Add custom alias
rtm item add-alias ic "item create"

# Remove custom alias
rtm item remove-alias ic
```

---

## Common Workflows

### Initialize New Project

```bash
# Create project
rtm project init my-project --description "My awesome project"

# Switch to project
rtm project switch my-project

# Create first epic
rtm item create "User Management" --view FEATURE --type epic
```

### Create Complete Feature

```bash
# Create epic
rtm item create "Authentication" --view FEATURE --type epic

# Create stories
rtm item create "Login Form" --view FEATURE --type story --parent EPIC-001
rtm item create "Password Reset" --view FEATURE --type story --parent EPIC-001

# Create code items
rtm item create "LoginComponent" --view CODE --type file
rtm item create "AuthService" --view CODE --type class

# Create links
rtm link create STORY-001 CODE-001 --type implements
rtm link create STORY-001 TEST-001 --type tests

# Check progress
rtm progress show --item EPIC-001
```

### Daily Workflow

```bash
# Check sync status
rtm sync status

# Pull latest changes
rtm sync pull

# Work on items
rtm item list --status todo --owner me
rtm item update STORY-001 --status in_progress

# Search for related work
rtm search "authentication" --view CODE

# Push changes
rtm sync push
```

---

## Tips and Best Practices

1. **Use External IDs**: Items are automatically assigned external IDs (EPIC-001, STORY-042, etc.) for easy reference
2. **Leverage Search**: Use `rtm search` for quick lookups, `rtm query` for structured queries
3. **Check Impact**: Before major changes, use `rtm link impact` to see what will be affected
4. **Monitor Progress**: Regularly check `rtm progress report` to track velocity
5. **Sync Frequently**: Run `rtm sync` often to avoid conflicts
6. **Use Filters**: Most list commands support filters to narrow results
7. **JSON Output**: Add `--json` to most commands for programmatic use
8. **Shell Completion**: Install shell completion for faster command entry

---

## Related Documentation

- [CLI Installation Guide](/docs/wiki/guides/cli-guide/installation)
- [CLI Configuration](/docs/wiki/guides/cli-guide/configuration)
- [API Reference](/docs/api-reference)
- [Sync Guide](/docs/wiki/guides/sync-guide)
