tx2-cli

Command-line interface for TX-2 ECS - inspect, debug, and manage TX-2 applications.

Installation

cargo install --path .

Or build from source:

cargo build --release

The binary will be available as tx2 (not tx2-cli).

Features

• Snapshot Management: List, inspect, export, diff, replay, and validate snapshots
• SQL Analytics: Query ECS data using SQLite, PostgreSQL, or DuckDB
• Live Connection: Connect to running TX-2 applications via WebSocket, stdio, or IPC
• Schema Tools: Generate, validate, diff, and migrate database schemas
• Development Tools: Generate test data, benchmark, profile, and fuzz test
• Project Scaffolding: Create new TX-2 projects from templates

Commands

Snapshot Commands

# List all snapshots in a directory
tx2 snapshot list ./snapshots

# Show detailed information about a snapshot
tx2 snapshot info snapshot_0001.snap

# Export snapshot to different format
tx2 snapshot export snapshot_0001.snap --format json --output snapshot.json
tx2 snapshot export snapshot_0001.snap --format parquet --output snapshot.parquet

# Compare two snapshots
tx2 snapshot diff snapshot_a.snap snapshot_b.snap --visual

# Replay snapshots as animation
tx2 snapshot replay ./snapshots --speed 2.0

# Validate snapshot integrity
tx2 snapshot validate snapshot_0001.snap

Query Commands

# Execute SQL query against SQLite database
tx2 query --db sqlite://game.db "SELECT * FROM entities LIMIT 10"

# Execute query against PostgreSQL
tx2 query --db postgresql://localhost/gamedb "SELECT entity_id, name FROM players"

# Execute query against DuckDB
tx2 query --db duckdb://analytics.db "SELECT * FROM entities WHERE created_at > '2024-01-01'"

# Interactive SQL REPL mode
tx2 query --db sqlite://game.db --interactive

# Save query results to file
tx2 query --db sqlite://game.db "SELECT * FROM entities" --output results.json --format json

Connect Commands

# Connect to running application via WebSocket
tx2 connect ws://localhost:8080

# Interactive REPL mode
tx2 connect ws://localhost:8080 --interactive

# TUI (Terminal UI) mode - interactive visual interface
tx2 connect ws://localhost:8080 --tui

# Connect via stdio
tx2 connect stdio://

# Connect via IPC
tx2 connect ipc:///tmp/tx2.sock

Schema Commands

# Generate schema from Rust source files
tx2 schema generate ./src --output schema.json

# Validate schema against database
tx2 schema validate schema.json --db sqlite://game.db

# Generate migration between two schemas
tx2 schema diff old_schema.json new_schema.json --output migration.sql

# Apply migration to database
tx2 schema migrate --db sqlite://game.db migration.sql

Development Commands

# Generate test entities
tx2 dev generate-entities --count 10000 --output test_data.snap

# Benchmark sync performance
tx2 dev benchmark-sync myapp --duration 60 --baseline baseline.json

# Profile memory usage
tx2 dev profile-memory myapp --duration 30

# Validate world consistency
tx2 dev validate snapshot_0001.snap

# Fuzz test snapshots
tx2 dev fuzz ./snapshots --iterations 1000

New Project Commands

# Create new application
tx2 new my-app --template app

# Create new game
tx2 new my-game --template game

# Create new multiplayer game
tx2 new my-multiplayer --template multiplayer

Network Commands

# Monitor network traffic in real-time
tx2 network monitor ws://localhost:8080

# Dump network messages to file
tx2 network dump ws://localhost:8080 --output traffic.jsonl

# Replay network dump
tx2 network replay traffic.jsonl --speed 1.0

# Analyze network dump statistics
tx2 network analyze traffic.jsonl

Output Formats

Most commands support multiple output formats via the --format flag:

• table (default): Pretty-printed tables
• json: Compact JSON
• json-pretty: Pretty-printed JSON
• csv: Comma-separated values
• yaml: YAML format

tx2 snapshot list ./snapshots --format json
tx2 query --db sqlite://game.db "SELECT * FROM entities" --format csv

Global Flags

• --format <FORMAT>: Output format (table, json, csv, yaml)
• --no-color: Disable colored output
• --verbose: Enable verbose output

Interactive Modes

Query REPL

tx2 query --db sqlite://game.db --interactive

REPL commands:

• .help - Show help
• .tables - List all tables
• .schema <table> - Show table schema
• .explain <query> - Explain query plan
• .analyze <table> - Analyze table statistics
• .exit or .quit - Exit REPL

Connect REPL

tx2 connect ws://localhost:8080 --interactive

REPL commands:

• .help - Show help
• .query <sql> - Execute ECS query
• .entities - List all entities
• .entity <id> - Show entity details
• .components - List component types
• .component <type> - List entities with component
• .snapshot - Create snapshot
• .stats - Show world statistics
• .ping - Ping the server
• .exit or .quit - Exit REPL

TUI (Terminal UI) Mode

tx2 connect ws://localhost:8080 --tui

The TUI mode provides a rich visual interface for inspecting ECS worlds:

Features:

• Live entity list with navigation (↑↓ or j/k keys)
• Component inspector showing selected entity's components
• Real-time updates from connected application
• Keyboard-driven interface

Controls:

• ↑/↓ or j/k - Navigate entity list
• q - Quit TUI mode
• r - Refresh data

Layout:

┌─────────────────────────────────────────────────────────────┐
│ TX-2 World Inspector - ws://localhost:8080                  │
├──────────────────┬──────────────────────────────────────────┤
│  Entities        │  Component Inspector                     │
│  > Entity_0      │  Entity: Entity_0                        │
│    Entity_1      │                                          │
│    Entity_2      │  Components:                             │
│    Entity_3      │                                          │
│    ...           │  Position:                               │
│                  │    x: 0.0, y: 0.0                        │
│                  │                                          │
│                  │  Velocity:                               │
│                  │    dx: 0.00, dy: 1.00                    │
│                  │                                          │
│                  │  Health:                                 │
│                  │    current: 100, max: 100                │
├──────────────────┴──────────────────────────────────────────┤
│ [q] Quit  [↑↓/jk] Navigate  [r] Refresh                    │
└─────────────────────────────────────────────────────────────┘

Examples

Analyze Game Performance

# Export snapshot to DuckDB for analytics
tx2 snapshot export snapshot_0100.snap --format duckdb --output analytics.db

# Query entity distribution
tx2 query --db duckdb://analytics.db "
  SELECT component_type, COUNT(*) as count
  FROM entities
  GROUP BY component_type
  ORDER BY count DESC
"

# Find entities with specific components
tx2 query --db duckdb://analytics.db "
  SELECT entity_id, component_data
  FROM entities
  WHERE component_type = 'Position'
"

Time-Travel Debugging

# List all snapshots
tx2 snapshot list ./snapshots --detailed

# Compare snapshots before and after bug
tx2 snapshot diff snapshot_0050.snap snapshot_0051.snap --visual

# Replay to visualize changes
tx2 snapshot replay ./snapshots --speed 0.5 --seek 50

Live Debugging

# Connect to running game
tx2 connect ws://localhost:8080 --interactive

# In REPL:
tx2> .entities
tx2> .entity 12345
tx2> .query SELECT * FROM entities WHERE health < 10
tx2> .snapshot

Configuration

tx2-cli stores history files in:

• Query REPL: ~/.local/share/tx2/query_history.txt
• Connect REPL: ~/.local/share/tx2/repl_history.txt

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Check without building
cargo check

Dependencies

• clap - Command-line argument parsing
• tabled - Table formatting
• colored - Terminal colors
• tokio - Async runtime
• rustyline - REPL line editing
• ratatui - Terminal UI framework
• crossterm - Terminal manipulation
• serde/serde_json/serde_yaml - Serialization
• tx2-pack - Snapshot management
• tx2-query - SQL analytics layer
• tx2-link - Network synchronization

License

MIT

Contributing

tx2-cli is part of the TX-2 ecosystem. For more information, see the main TX-2 repository.