# tx2-cli
Command-line interface for TX-2 ECS - inspect, debug, and manage TX-2 applications.
## Installation
```bash
cargo install --path .
```
Or build from source:
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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.