Installing the `tx2` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install tx2-cli

It will make the tx2 command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall tx2-cli uninstalls.

Back to the crate overview.

Readme

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.

Installing the tx2 executable

Installing the `tx2` executable