Output Formats

TONL CLI supports multiple output formats to accommodate different workflows, from human-readable reports to machine-parseable data for automation.

Available Formats

Format	Use Case	Human Readable	Machine Parseable
Text	Terminal output	Excellent	Poor
JSON	Automation, CI/CD	Poor	Excellent
Markdown	Documentation, PRs	Excellent	Partial
CSV	Spreadsheets, reports	Good	Excellent
Visual	Presentations	Excellent	No

Text Format

The default output format provides clear, structured information in plain text.

Usage

tonl analyze data.json

Output Structure

📊 Analysis for data.json

Model:           GPT-4o (OpenAI)
Token Usage:
  JSON:          477 tokens
  TONL:          255 tokens
  ✅ Saved:       222 tokens (46.5%)

Costs (per 1M requests):
  ❌ JSON:        $1192.50
  ✅ TONL:        $637.50
  💰 Savings:     $555.00 (46.5%)

When to Use

• Quick terminal checks
• Manual analysis
• Debugging
• Development workflow

Text format is not suitable for automation or parsing by other tools.

JSON Format

Machine-readable format suitable for automation and programmatic processing.

Usage

tonl analyze data.json --format json

Output Structure

[
  {
    "file": "data.json",
    "model": {
      "name": "GPT-4o",
      "provider": "OpenAI",
      "inputCost": 2.5
    },
    "jsonTokens": 477,
    "tonlTokens": 255,
    "savingsPercent": 46.5,
    "costs": {
      "json": {
        "per1K": 1.1925,
        "per1M": 1192.5
      },
      "tonl": {
        "per1K": 0.6375,
        "per1M": 637.5
      },
      "savings": {
        "per1K": 0.555,
        "per1M": 555
      }
    },
    "annualSavingsAt1KPerDay": 202.575,
    "recommendation": "STRONGLY_USE_TONL"
  }
]

Field Reference

Top Level:

• file - Analyzed file path
• model - LLM model information
• jsonTokens - Token count for JSON format
• tonlTokens - Token count for TONL format
• savingsPercent - Percentage savings
• costs - Detailed cost breakdown
• annualSavingsAt1KPerDay - Projected annual savings
• recommendation - Automated recommendation

Model Object:

• name - Model display name
• provider - Provider name (OpenAI, Anthropic, Google)
• inputCost - Cost per 1M input tokens

Costs Object:

• json.per1K - JSON cost per 1,000 requests
• json.per1M - JSON cost per 1,000,000 requests
• tonl.per1K - TONL cost per 1,000 requests
• tonl.per1M - TONL cost per 1,000,000 requests
• savings.per1K - Savings per 1,000 requests
• savings.per1M - Savings per 1,000,000 requests

When to Use

CI/CD Pipelines

# Generate metrics
tonl analyze data.json --format json > metrics.json

# Extract specific values
savings=$(cat metrics.json | jq '.[0].savingsPercent')
echo "Token savings: ${savings}%"

Automated Testing

# Verify savings threshold
savings=$(tonl analyze data.json --format json | jq '.[0].savingsPercent')
if (( $(echo "$savings < 40" | bc -l) )); then
  echo "Warning: Savings below 40% threshold"
  exit 1
fi

Data Processing

const fs = require('fs');
const analysis = JSON.parse(fs.readFileSync('analysis.json'));

analysis.forEach(result => {
  if (result.savingsPercent > 50) {
    console.log(`High savings in ${result.file}`);
  }
});

Monitoring Systems

# Send to monitoring endpoint
tonl analyze data.json --format json | \
  curl -X POST https://monitoring.example.com/metrics \
    -H "Content-Type: application/json" \
    -d @-

Markdown Format

Human-readable format optimized for documentation and reports.

Usage

tonl analyze data.json --format markdown

Single File Output

# 🚀 TONL ROI Analysis Report

**Generated:** 2024-12-03T10:30:00Z

## 📊 Analysis Summary

- **File:** `data.json`
- **Model:** GPT-4o (OpenAI)
- **Token Savings:** 46.5%

## 📈 Token Usage

| Format | Tokens | Change |
|--------|--------|--------|
| JSON | 477 | - |
| TONL | 255 | -222 (-46.5%) |

## 💰 Cost Analysis

| Metric | JSON | TONL | Savings |
|--------|------|------|---------|
| Per 1K requests | $1.19 | $0.64 | **$0.55** |
| Per 1M requests | $1,192.50 | $637.50 | **$555.00** |

### 💎 $202.57 per year savings
*Projection based on 1,000 requests per day*

## ✅ Recommendation

**STRONGLY USE TONL** - Token savings exceed 20%, indicating significant cost reduction potential.

---

*Generated by TONL CLI v1.0.0 on 2024-12-03T10:30:00Z*

Batch Analysis Output

When analyzing multiple files, Markdown format generates a summary report:

# 🚀 TONL Batch Analysis Report

**Generated:** 2024-12-03T10:30:00Z  
**Files Analyzed:** 3

## 📊 Summary Statistics

- **Total Savings:** 48.2%
- **Average Annual Savings:** $612.43
- **Total Files:** 3

## 📈 Per-File Results

| File | Model | Savings % | Annual Savings |
|------|-------|-----------|----------------|
| products.json | GPT-4o | 52.1% | $189.77 |
| users.json | GPT-4o | 46.5% | $202.57 |
| orders.json | GPT-4o | 45.9% | $220.09 |

---

*Generated by TONL CLI v1.0.0*

When to Use

GitHub Pull Requests

# Generate analysis
tonl analyze changed-files/*.json --format markdown > analysis.md

# Post as PR comment
gh pr comment $PR_NUMBER -F analysis.md

Documentation Sites

# Generate reports for docs
tonl analyze examples/*.json --format markdown > docs/analysis.md

Email Reports

# Create readable reports
tonl analyze data/*.json --format markdown > weekly-report.md

Confluence/Notion

Markdown output can be directly pasted into most documentation platforms with proper formatting preserved.

CSV Format

Spreadsheet-compatible format designed for financial reporting and executive presentations.

Usage

tonl analyze data.json --format csv

Or use the export flag:

tonl analyze data.json --export report.csv

Structure

The Smart Enterprise CSV format contains 12 columns optimized for business reporting:

Timestamp,File,Model,Currency,Original Tokens,TONL Tokens,Savings %,Cost per 1K (JSON),Cost per 1K (TONL),Net Savings per 1M,Annual Savings @ 1K/day,Recommendation
2024-12-03T10:30:00Z,data.json,GPT-4o,USD,477,255,46.5,$1.19,$0.64,$555.00,$202.57,STRONGLY_USE_TONL

Column Reference

Context Columns (1-4):

1. Timestamp - Analysis timestamp (ISO 8601)
2. File - Source file name
3. Model - LLM model name
4. Currency - Display currency code

Hard Facts (5-9): 5. Original Tokens - JSON token count 6. TONL Tokens - TONL token count 7. Savings % - Percentage reduction 8. Cost per 1K (JSON) - JSON cost per 1,000 requests 9. Cost per 1K (TONL) - TONL cost per 1,000 requests

Money Shot (10-12): 10. Net Savings per 1M - Savings per million requests 11. Annual Savings @ 1K/day - Projected yearly savings 12. Recommendation - Automated recommendation

When to Use

Executive Dashboards

# Generate executive report
tonl analyze production-data.json --export executive-report.csv

Import into Excel, Google Sheets, or BI tools for further analysis and visualization.

Budget Planning

# Analyze all project files
tonl analyze "src/**/*.json" --export budget-analysis.csv

Use in financial planning spreadsheets to project cost reductions.

Quarterly Reports

# Generate quarterly analysis
tonl analyze q4-data/*.json --export q4-token-analysis.csv

Include in quarterly business reviews and cost optimization reports.

CFO Presentations

The 12-column format provides all necessary context, hard numbers, and business impact in a format familiar to financial stakeholders.

Multi-Currency Support

All formats support currency conversion:

# EUR
tonl analyze data.json --currency EUR --format markdown

# JPY
tonl analyze data.json --currency JPY --export report.csv

# GBP
tonl analyze data.json --currency GBP --format json

Supported currencies: USD, EUR, GBP, JPY, CHF, CAD, AUD

Custom exchange rates:

tonl analyze data.json --currency EUR --rate 0.95 --format csv

Format Comparison

Text vs Visual

• Text: Quick checks, scripting, logging
• Visual: Presentations, demos, stakeholder meetings

JSON vs CSV

• JSON: Automation, APIs, nested data
• CSV: Spreadsheets, financial analysis, flat data

Markdown vs CSV

• Markdown: Documentation, reports, wikis
• CSV: Data analysis, charts, pivot tables

Best Practices

Combine Multiple Formats

Generate different outputs for different audiences:

# For engineering
tonl analyze data.json --format json > metrics.json

# For documentation
tonl analyze data.json --format markdown > README.md

# For finance
tonl analyze data.json --export financial-report.csv

Use Appropriate Format for Workflow

Development:

tonl analyze data.json  # Default text

CI/CD:

tonl analyze data.json --format json

Stakeholder Reports:

tonl analyze data.json --export report.csv

Redirect vs Export Flag

For CSV, both methods work:

# Redirect (cross-platform)
tonl analyze data.json --format csv > report.csv

# Export flag (recommended)
tonl analyze data.json --export report.csv

The export flag is recommended as it provides better error handling and file writing feedback.

Integration Examples

GitHub Actions

- name: Generate Analysis
  run: |
    tonl analyze fixtures/**/*.json --format markdown > analysis.md
    tonl analyze fixtures/**/*.json --format json > metrics.json
    
- name: Upload Artifacts
  uses: actions/upload-artifact@v3
  with:
    name: analysis-reports
    path: |
      analysis.md
      metrics.json

Jenkins Pipeline

stage('TONL Analysis') {
    steps {
        sh 'tonl analyze data/*.json --export analysis.csv'
        archiveArtifacts artifacts: 'analysis.csv'
    }
}

GitLab CI

tonl-analysis:
  script:
    - tonl analyze data/*.json --format markdown > analysis.md
    - tonl analyze data/*.json --format json > metrics.json
  artifacts:
    paths:
      - analysis.md
      - metrics.json

Next Steps

• CLI Reference - Complete command documentation
• ROI Calculator - Detailed analysis options
• Visual Dashboard - Interactive terminal UI