Skip to content

CLI Reference

Jump to bottom
rUv edited this page Jul 31, 2025 · 1 revision

CLI Reference

Complete command-line interface documentation for FACT across all platforms.

📚 Table of Contents

Python CLI

The Python CLI provides comprehensive access to FACT's financial data analysis capabilities.

Basic Usage

# Start interactive mode (default)
python main.py

# Process single query
python main.py --query "What is TechCorp's revenue?"

# Initialize system
python main.py init

# Run demo
python main.py demo

Commands

init - Initialize FACT System

python main.py init

Initializes the database schema, validates configuration, and prepares the system for use.

demo - Run Demonstration

python main.py demo

Runs example queries to demonstrate FACT capabilities.

interactive - Interactive Mode

python main.py interactive
# or simply
python main.py

Starts the interactive query interface.

Interactive Mode Commands

Once in interactive mode:

💬 > help              # Show available commands
💬 > status            # Display system status
💬 > cache stats       # Show cache statistics
💬 > cache clear       # Clear cache
💬 > tools list        # List available tools
💬 > history           # Show query history
💬 > export [file]     # Export results
💬 > exit              # Exit interactive mode

Query Options

# Basic query
python main.py --query "List all companies"

# With output format
python main.py --query "Get revenue data" --format json

# With cache control
python main.py --query "Analyze trends" --no-cache

# With debug output
python main.py --query "Complex analysis" --debug

Rust CLI (fact-tools)

The Rust CLI offers high-performance processing with cognitive templates.

Installation

# Install from crates.io
cargo install fact-tools

# Or build from source
cd cargo-crate
cargo build --release

Basic Usage

# Process with template
fact process data.json --template analysis-basic

# List templates
fact templates list

# Cache operations
fact cache stats

# Run benchmarks
fact benchmark

# Initialize configuration
fact init

Commands

process - Process Data

# Basic processing
fact process input.json

# With specific template
fact process data.json --template pattern-detection

# With output file
fact process input.json --output results.json

# Streaming mode
cat data.json | fact process --stream

templates - Template Management

# List available templates
fact templates list

# Show template details
fact templates show analysis-basic

# Search templates
fact templates search "pattern"

# Create custom template
fact templates create my-template --file template.json

cache - Cache Management

# Show cache statistics
fact cache stats

# Clear cache
fact cache clear

# Set cache size
fact cache resize 1000

# Export cache
fact cache export cache-dump.json

# Import cache
fact cache import cache-dump.json

benchmark - Performance Testing

# Run default benchmark
fact benchmark

# Custom iterations
fact benchmark --iterations 10000

# Specific operations
fact benchmark --operations cache,template

# Output results
fact benchmark --output bench-results.json

init - Initialize Configuration

# Create default config
fact init

# With custom path
fact init --config-path ./my-config.json

# Interactive setup
fact init --interactive

Configuration

Create fact.json in your project root:

{
  "cache": {
    "max_size": 10000,
    "ttl_seconds": 3600,
    "eviction_policy": "lru"
  },
  "templates": {
    "default": "analysis-basic",
    "custom_path": "./templates"
  },
  "performance": {
    "parallel_operations": true,
    "max_threads": 8
  }
}

Common Options

Options available across both CLIs:

Global Flags

--help, -h              # Show help information
--version, -v           # Display version
--config, -c <file>     # Use custom config file
--verbose               # Enable verbose output
--debug                 # Enable debug output
--quiet, -q            # Suppress non-error output

Environment Variables

# Python
export ANTHROPIC_API_KEY="your-key"
export ARCADE_API_KEY="your-key"
export FACT_DB="custom.db"
export FACT_CACHE_PREFIX="myapp"
export FACT_LOG_LEVEL="DEBUG"

# Rust
export FACT_CONFIG_PATH="/path/to/config.json"
export FACT_CACHE_DIR="/path/to/cache"
export FACT_LOG_LEVEL="debug"
export RUST_LOG="fact=debug"

Query Processing

Query Syntax

Both CLIs support natural language queries:

# Financial queries
"What is the revenue for Q1 2025?"
"Show me technology sector companies"
"Calculate growth rate for TechCorp"

# Data analysis
"Analyze trends in financial data"
"Compare performance metrics"
"Generate quarterly report"

Query Options

# Python
--query-timeout 30      # Timeout in seconds
--max-results 100       # Limit results
--cache-only           # Use cache only
--fresh-data           # Skip cache

# Rust
--timeout 30           # Processing timeout
--limit 100           # Result limit
--parallel            # Enable parallel processing

Cache Management

Cache Commands

# Python CLI
python main.py cache stats
python main.py cache clear
python main.py cache export cache.json
python main.py cache import cache.json

# Rust CLI
fact cache stats --detailed
fact cache clear --confirm
fact cache optimize
fact cache warm data.json

Cache Configuration

# Set cache size (Python)
export FACT_CACHE_MAX_SIZE=10000

# Set cache TTL (Python)
export FACT_CACHE_TTL=3600

# Configure Rust cache
fact cache config --max-size 10000 --ttl 3600

Benchmarking

Performance Testing

# Python benchmarks
python -m benchmarking.framework --suite all
python -m benchmarking.framework --suite cache --iterations 1000

# Rust benchmarks
fact benchmark --full
fact benchmark --operations cache,template,process
fact benchmark --compare baseline.json

Benchmark Output

{
  "timestamp": "2025-07-31T20:00:00Z",
  "operations": {
    "cache_hit": {
      "ops_per_sec": 40000,
      "avg_latency_ms": 0.025
    },
    "template_process": {
      "ops_per_sec": 6667,
      "avg_latency_ms": 0.15
    }
  }
}

Configuration

Configuration Files

# Python configuration
.env                    # Environment variables
config/config.yaml      # Application config
config/logging.yaml     # Logging config

# Rust configuration
fact.json              # Main config
templates/             # Custom templates
cache/                # Cache directory

Dynamic Configuration

# Python - Update at runtime
python main.py config set cache.max_size 5000
python main.py config get cache.max_size
python main.py config list

# Rust - Config commands
fact config set cache.max_size 5000
fact config get cache.max_size
fact config validate

Output Formats

Supported Formats

# Python formats
--format json          # JSON output
--format csv          # CSV output
--format table        # Formatted table (default)
--format markdown     # Markdown table
--format yaml         # YAML output

# Rust formats
--output-format json   # JSON output
--output-format csv    # CSV output
--output-format pretty # Pretty printed (default)
--output-format binary # Binary format

Format Examples

# JSON output
python main.py --query "Get data" --format json | jq .

# CSV for spreadsheets
python main.py --query "Export records" --format csv > data.csv

# Markdown for documentation
fact process data.json --output-format markdown > results.md

Scripting Examples

Bash Scripting

#!/bin/bash
# fact-daily-report.sh

# Process daily data
echo "Processing daily financial data..."
python main.py --query "Generate daily report" --format json > daily-report.json

# Check cache health
CACHE_STATS=$(python main.py cache stats --format json)
HIT_RATE=$(echo $CACHE_STATS | jq .hit_rate)

if (( $(echo "$HIT_RATE < 0.8" | bc -l) )); then
    echo "Warning: Cache hit rate below 80%"
    python main.py cache optimize
fi

# Archive results
tar -czf "reports/daily-$(date +%Y%m%d).tar.gz" daily-report.json

Python Scripting

#!/usr/bin/env python3
# fact_batch_processor.py

import subprocess
import json
from datetime import datetime

queries = [
    "Analyze Q1 revenue",
    "Calculate growth metrics",
    "Generate executive summary"
]

results = {}
for query in queries:
    output = subprocess.run(
        ["python", "main.py", "--query", query, "--format", "json"],
        capture_output=True,
        text=True
    )
    results[query] = json.loads(output.stdout)

# Save consolidated report
with open(f"report_{datetime.now():%Y%m%d}.json", "w") as f:
    json.dump(results, f, indent=2)

Rust Integration

// fact_automation.rs
use std::process::Command;
use serde_json::Value;

fn main() {
    // Process with fact CLI
    let output = Command::new("fact")
        .args(&["process", "data.json", "--template", "analysis-basic"])
        .output()
        .expect("Failed to execute fact");

    let result: Value = serde_json::from_slice(&output.stdout)
        .expect("Failed to parse output");

    println!("Processing complete: {:?}", result);
}

CI/CD Integration

# .github/workflows/fact-analysis.yml
name: FACT Analysis

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install FACT
        run: |
          pip install fact-system
          cargo install fact-tools
      
      - name: Run Analysis
        run: |
          python main.py init
          python main.py --query "Daily analysis" --format json > results.json
          fact benchmark --output benchmark.json
      
      - name: Upload Results
        uses: actions/upload-artifact@v2
        with:
          name: fact-results
          path: |
            results.json
            benchmark.json

Tips and Tricks

Performance Optimization

# Warm cache before heavy processing
python main.py cache warm --data historical.json

# Use parallel processing in Rust
fact process large-dataset.json --parallel --threads 8

# Batch queries for efficiency
cat queries.txt | python main.py --batch --format json

Debugging

# Enable debug logging
export FACT_LOG_LEVEL=DEBUG
python main.py --debug --query "Complex query"

# Rust debug output
RUST_LOG=fact=debug fact process data.json

# Trace execution
python main.py --trace --query "Slow query" 2> trace.log

Advanced Usage

# Chain operations
python main.py --query "Extract data" | \
  fact process --stream --template transform | \
  python main.py --query "Analyze results"

# Custom templates
fact process data.json --template ./my-templates/custom.json

# Export for other tools
python main.py --query "Export all" --format csv | \
  csvkit --stats > analysis.txt

This CLI reference provides comprehensive documentation for using FACT from the command line across both Python and Rust implementations.

Clone this wiki locally