Skip to content

tui-usage.md

Latest commit

 

History

History
567 lines (425 loc) · 18.4 KB

tui-usage.md

File metadata and controls

567 lines (425 loc) · 18.4 KB

Terraphim Terminal User Interface (TUI)

Terraphim includes a comprehensive terminal user interface (TUI) that provides both interactive REPL functionality and CLI commands for advanced operations including VM management, web operations, and intelligent file operations with semantic awareness. The TUI is ideal for CI/CD environments, headless servers, development workflows, and integration with terminal-based automation.

Installation

Prerequisites

  • Rust toolchain (cargo)
  • Running Terraphim server (local or remote)

Building from Source

Build the TUI from the workspace with optional feature flags:

# Clone the repository (if you haven't already)
git clone https://github.com/terraphim/terraphim-ai.git
cd terraphim-ai

# Build with all features (recommended)
cargo build -p terraphim_tui --features repl-full --release

# Build with specific features
cargo build -p terraphim_tui --features repl,repl-chat,repl-file,repl-mcp --release

# Build minimal TUI (basic functionality only)
cargo build -p terraphim_tui --release

# The binary will be available at
# ./target/release/terraphim-tui

Feature Flags

The TUI supports modular feature flags for different capabilities:

  • repl - Basic REPL functionality and search commands
  • repl-chat - AI chat integration with OpenRouter and Ollama
  • repl-file - Enhanced file operations with semantic awareness
  • repl-mcp - Model Context Protocol (MCP) tools integration
  • repl-full - All features enabled (recommended)

Example: Install with chat and file operations:

cargo install --path crates/terraphim_tui --features repl-chat,repl-file

Configuration

Set the Terraphim server URL (defaults to http://localhost:8000):

export TERRAPHIM_SERVER=http://localhost:8000

This environment variable is required for the TUI to connect to the server. If not set, the default will be used.

Command Reference

Interactive REPL Mode

The TUI features a comprehensive REPL (Read-Eval-Print Loop) that provides access to all advanced functionality:

terraphim-tui

In interactive mode, you have access to:

  • Smart Search: Type queries and get intelligent suggestions from the rolegraph
  • VM Management: Control Firecracker VMs for isolated operations
  • Web Operations: Perform web requests through secure VM sandboxing
  • File Operations: Intelligent file management with semantic analysis
  • AI Chat: Integrated AI assistant with context awareness
  • Configuration: Real-time role and configuration management
  • Help System: Built-in command help and suggestions

REPL Commands

Navigation and Help:

/help                    # Show all available commands
/quit                    # Exit the REPL
/clear                   # Clear the screen

Search and Knowledge:

/search "async rust"     # Search with semantic understanding
/graph                   # Show rolegraph visualization
/roles list              # List available roles
/role select Developer   # Switch to Developer role

VM Management:

/vm list                 # List all VMs
/vm create my-vm         # Create new VM
/vm start my-vm          # Start VM
/vm stop my-vm           # Stop VM
/vm status my-vm         # Check VM status
/vm logs my-vm           # View VM logs

Web Operations:

/web get https://api.example.com/data
/web post https://api.example.com/submit '{"data": "value"}'
/web scrape https://example.com '.content'
/web screenshot https://example.com
/web pdf https://example.com/article
/web history             # View operation history

File Operations (Semantic):

/file search "error handling" --path ./src --semantic
/file classify ./src --recursive --update-metadata
/file analyze ./main.rs --classification --extract-entities
/file summarize ./README.md --detailed --key-points
/file tag ./lib.rs rust,core,module --auto-suggest
/file index ./docs --recursive
/file metadata ./src/main.rs --extract-concepts

AI Chat:

/chat "Explain async patterns in Rust" --role Developer
/chat "Help me debug this issue" --context ./src/main.rs

Search Command

Search for documents using the CLI:

terraphim-tui search --query "terraphim-graph" --role "Default" --limit 10

Parameters:

  • --query (required): The search term or phrase
  • --role (optional): Role name to use for search context (default: "Default")
  • --limit (optional): Maximum number of results to return (default: 10)

Example output:

- 0.95    Introduction to Terraphim Graph
- 0.82    Graph-based Knowledge Representation
- 0.75    Implementing Graph Algorithms

Roles Management

List available roles:

terraphim-tui roles list

Select a role for future queries:

terraphim-tui roles select "Engineer"

Configuration Commands

Display current configuration:

terraphim-tui config show

Update configuration settings:

# Change selected role
terraphim-tui config set selected_role=Engineer

# Update global shortcut
terraphim-tui config set global_shortcut=Ctrl+X

# Change theme for a specific role
terraphim-tui config set role.Default.theme=spacelab

Rolegraph Visualization

Display ASCII representation of the rolegraph:

terraphim-tui graph --role "Default" --top-k 10

Parameters:

  • --role (optional): Role name to visualize (default: "Default")
  • --top-k (optional): Number of top nodes to display (default: 50)

Example output:

Nodes: 1250  Edges: 3750
- [95] terraphim-graph -> knowledge representation, semantic networks, graph theory, ontology, rolegraph
- [87] knowledge management -> information retrieval, knowledge base, organization, metadata, taxonomy
- [76] graph database -> neo4j, arangodb, knowledge graph, query language, traversal

Chat Command (AI Integration)

Interact with AI models through OpenRouter or Ollama:

# REPL mode
/chat "Explain async patterns in Rust" --role Developer

# CLI mode
terraphim-tui chat --role "Default" --prompt "Summarize terraphim graph" --model anthropic/claude-3-sonnet

Parameters:

  • --prompt (required): The message to send to the AI
  • --role (optional): Role context to use (default: "Default")
  • --model (optional): Specific model to use (overrides role default)
  • --context (optional): File or directory to provide as context

Supported AI Providers:

  • OpenRouter: Multiple models including Claude, GPT, Llama (requires OPENROUTER_KEY)
  • Ollama: Local models (requires OLLAMA_BASE_URL)

VM Management (Firecracker Integration)

Manage isolated Firecracker virtual machines for secure operations:

# List all VMs and their status
/vm list

# Create a new VM with specific configuration
/vm create my-dev-vm --cpu 2 --memory 2048 --image ubuntu

# Start and stop VMs
/vm start my-dev-vm
/vm stop my-dev-vm
/vm restart my-dev-vm

# Monitor VM status and resources
/vm status my-dev-vm
/vm metrics my-dev-vm

# View logs and connect to VM
/vm logs my-dev-vm
/vm shell my-dev-vm

# VM pool management
/vm pool list
/vm pool create dev-pool --size 3 --cpu 2 --memory 2048

VM Features:

  • Isolated Execution: Secure sandboxing for sensitive operations
  • Resource Management: CPU, memory, and storage allocation
  • Lifecycle Control: Start, stop, pause, and restart operations
  • Monitoring: Real-time metrics and health status
  • Integration: Seamless integration with web and file operations

Web Operations (VM-Sandboxed)

Perform web operations through secure VM isolation:

# HTTP requests
/web get https://api.example.com/data
/web post https://api.example.com/submit '{"data": "value"}' --headers "Content-Type: application/json"

# Web scraping and content extraction
/web scrape https://example.com '.content' --selector '.article'
/web screenshot https://example.com --full-page --wait 2000
/web pdf https://example.com/article --output article.pdf

# Form interactions
/web form https://example.com/login '{"username": "user", "password": "pass"}' --submit

# API exploration
/web api https://api.github.com /users/user1,/repos/repo1 --auth token

# Operation management
/web history
/web status webop-1642514400000
/web cancel webop-1642514400000

# Configuration
/web config show
/web config set timeout_ms 45000
/web config set user_agent "Terraphim-TUI/1.0"

Web Operation Features:

  • VM Sandboxing: All requests run in isolated Firecracker VMs
  • Security: No direct network access from host system
  • Versatility: GET, POST, scraping, screenshots, PDF generation
  • Authentication: Support for API keys, tokens, and form-based auth
  • Operation Tracking: History, status monitoring, and cancellation

File Operations (Semantic Intelligence)

Intelligent file operations with semantic understanding and analysis:

# Semantic file search
/file search "error handling" --path ./src --semantic --limit 10
/file search "async patterns" --file-types rs,js --recursive

# Content-based classification
/file classify ./src --recursive --update-metadata
/file analyze ./main.rs --classification --semantic --extract-entities

# Content summarization
/file summarize ./README.md --detailed --key-points
/file summarize ./docs/api.md --brief

# Semantic metadata extraction
/file metadata ./src/main.rs --extract-concepts --extract-entities --extract-keywords

# Intelligent file indexing
/file index ./docs --recursive --force-reindex
/file find "function_name" --path ./src --type rs

# Smart file listing
/file list ./src --show-metadata --show-tags --sort-by name
/file list ./src --sort-by relevance --limit 20

# Semantic file tagging
/file tag ./lib.rs rust,core,module --auto-suggest
/file suggest --context "error handling" --limit 5

# Operation status
/file status indexing
/file status classification

File Operation Features:

  • Semantic Search: Understanding of content meaning, not just text matching
  • Content Classification: Automatic detection of file types, languages, frameworks
  • Metadata Extraction: Concepts, entities, keywords, complexity metrics
  • Relationship Discovery: Find related files based on content similarity
  • Smart Tagging: Automatic tag suggestions based on content analysis
  • Performance Analysis: Reading time estimation and complexity scoring

File Categories Supported:

  • Code: Language detection (Rust, JavaScript, Python, etc.) with framework identification
  • Documentation: Markdown, HTML, text files with complexity analysis
  • Configuration: JSON, YAML, TOML, XML with purpose inference
  • Data: CSV, JSON data files with structure analysis
  • Media: Images, videos, audio files with metadata extraction
  • Archives: ZIP, TAR, GZ with content type detection
  • Scripts: Shell scripts, batch files with purpose analysis

Configuration Requirements

Environment Variables

Variable Required Default Description
TERRAPHIM_SERVER Yes http://localhost:8000 URL of the Terraphim server
OPENROUTER_KEY No None OpenRouter API key for chat functionality
OLLAMA_BASE_URL No http://127.0.0.1:11434 Ollama server URL for local models
VM_STORAGE_PATH No ./vm-storage Directory for VM disk images
VM_NETWORK_BRIDGE No virbr0 Network bridge for VM networking
WEB_OPERATION_TIMEOUT No 30000 Default timeout for web operations (ms)
FILE_INDEX_PATH No ./file-index Directory for file operation indexes

VM Configuration

The VM management requires Firecracker and proper system configuration:

# Install Firecracker (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y firecracker

# Set up kernel permissions for microVMs
sudo sysctl -w vm.nr_hugepages=1024
sudo chmod 666 /dev/kvm
sudo chown $USER:$USER /dev/kvm

# Create VM storage directory
mkdir -p ./vm-storage
chmod 755 ./vm-storage

VM Requirements:

  • Linux kernel with KVM support
  • Firecracker binary installed
  • Proper permissions for /dev/kvm and /dev/vhost-net
  • Sufficient memory and CPU for microVMs

MCP Tools Configuration

For Model Context Protocol integration:

# Set MCP server URL (optional)
export MCP_SERVER_URL=http://localhost:3001

# Set MCP authentication token (if required)
export MCP_AUTH_TOKEN=your-mcp-token

Server Requirements

The TUI requires a running Terraphim server with the following endpoints:

  • /config - Configuration management
  • /config/selected_role - Role selection
  • /documents/search - Document search
  • /rolegraph - Role graph data
  • /chat - AI chat functionality (optional)
  • /documents/summarize - AI-powered document summarization (optional)

Feature-specific server requirements:

  • Chat functionality: Server compiled with openrouter feature flag
  • VM operations: Firecracker integration and proper system permissions
  • File operations: Sufficient disk space for indexes and metadata
  • Web operations: Network connectivity through VM sandboxing

Known Limitations

OpenRouter Feature Flag

The chat functionality requires the server to be compiled with the openrouter feature flag:

# Server must be built with OpenRouter support
cargo build --package terraphim_server --features openrouter

Without this feature flag enabled during server compilation, the chat command will return an error.

External Service Timeouts

  • Server Connection: If the Terraphim server is unreachable, operations will time out after approximately 30 seconds
  • OpenRouter API: Chat requests may time out after 60 seconds for complex or long requests
  • VM Operations: VM startup and shutdown may take 10-30 seconds depending on system resources
  • Web Operations: Timeout configurable via WEB_OPERATION_TIMEOUT (default: 30 seconds)
  • File Indexing: Large repositories may require significant time for initial indexing
  • Network Connectivity: Intermittent network issues may cause unexpected behavior

Command Support Limitations

  • Configuration editing is limited to selected_role, global_shortcut, and role themes
  • Chat functionality lacks streaming responses (planned for future releases)
  • ASCII graph visualization is limited to basic node-neighbor representation
  • VM operations require root privileges and proper KVM setup
  • File operations are currently read-only (no file modification capabilities)
  • Web operations through VMs may have limited JavaScript execution support

Platform Limitations

  • VM Management: Currently only supported on Linux with KVM support
  • Firecracker: Requires specific kernel configurations and permissions
  • File Operations: Semantic analysis optimized for code and documentation files
  • Web Scraping: Complex single-page applications may have limited support

Resource Requirements

  • VM Operations: Minimum 2GB RAM recommended for running microVMs
  • File Indexing: Disk space required for semantic indexes (varies by repository size)
  • Web Operations: Memory usage scales with the complexity of web pages processed

Integration with Terraphim Ecosystem

The TUI seamlessly integrates with the broader Terraphim ecosystem:

Server Compatibility

The TUI is compatible with:

  • Standard Terraphim server
  • Custom server implementations that adhere to the API endpoints
  • Cloud-hosted Terraphim instances

Data Access

  • Leverages the same rolegraph and knowledge base as the desktop application
  • Uses identical search algorithms and relevance functions
  • Maintains consistent role-based context switching

Workflow Integration

The TUI can be integrated into existing workflows:

  • CI/CD pipelines for knowledge retrieval
  • Shell scripts for automated searches
  • Terminal-based development environments

Example Integration Scripts

Build Script Integration:

#!/bin/bash
# Example of integrating Terraphim TUI into a build script

export TERRAPHIM_SERVER="http://knowledge.internal.example.com:8000"

# Run search and capture results
SEARCH_RESULTS=$(terraphim-tui search --query "deployment best practices" --role "DevOps" --limit 5)

# Process results
if echo "$SEARCH_RESULTS" | grep -q "deployment automation"; then
  echo "Found deployment automation documentation"
  # Additional processing...
fi

Code Review Automation:

#!/bin/bash
# Automated code analysis using TUI file operations

# Classify files in the repository
terraphim-tui file classify ./src --recursive --update-metadata

# Find potential issues
terraphim-tui file search "TODO" "FIXME" --path ./src --semantic

# Generate summary of changes
terraphim-tui file summarize ./CHANGELOG.md --detailed

Security Analysis:

#!/bin/bash
# Security analysis using VM-sandboxed web operations

# Check dependencies for known vulnerabilities
terraphim-tui web get "https://api.github.com/advisories?ecosystem=npm" --auth "$GITHUB_TOKEN"

# Scan web application securely
terraphim-tui web screenshot "https://app.example.com" --full-page
terraphim-tui web scrape "https://app.example.com" '.security-info'

Roadmap

Near-term (Next 3 months)

  • Enhanced VM Management: VM snapshots, cloning, and migration
  • Streaming Chat: Real-time streaming responses in the TUI
  • File Editing: Safe file modification capabilities with backup
  • Advanced Web Scraping: JavaScript execution and dynamic content support
  • Performance Improvements: Optimized indexing and caching

Medium-term (3-6 months)

  • Cross-platform VM Support: Windows and macOS VM management
  • Collaborative Features: Shared sessions and real-time collaboration
  • Advanced Analytics: Usage statistics and performance metrics
  • Plugin System: Extensible architecture for custom operations
  • Enhanced Security: Certificate management and secure enclaves

Long-term (6+ months)

  • GUI Integration: Seamless integration with desktop application
  • Mobile Support: Mobile-friendly interface and capabilities
  • Cloud Integration: Direct cloud service integrations (AWS, GCP, Azure)
  • AI-Powered Automation: Intelligent workflow automation
  • Enterprise Features: SSO, audit logging, and compliance tools

Community Contributions

We welcome contributions for:

  • Language Support: Expanding semantic analysis to more programming languages
  • Documentation: Improving documentation and adding examples
  • Testing: Comprehensive test coverage for all features
  • Performance: Optimization and benchmarking improvements
  • Accessibility: Making the TUI more accessible to all users