Introduction

Welcome to the CSVREPORT User Manual.

CSVREPORT is a high-performance precision tool for CSV files, designed to analyze, validate, and report on datasets of any size with minimal memory consumption.

Components

• CLI Tool: For power users, developers, and automation in data pipelines.
• Web App: For visual analysis, easy uploads, and managing historical reports.

This manual will guide you through installing, configuring, and using both components effectively.

Quickstart

Getting up and running with CSVREPORT is simple.

Installation

1. Extract the archive: Download the csvreport-vX.Y.Z.zip file and extract it. Inside, you will find .tar.gz bundles for different operating systems. Extract the one that matches your system.
2. Run the binary:
   • For CLI: ./csvreport --help
   • For Web App: ./csvreport ui

First Steps

Analyze your first CSV via CLI

./csvreport my_data.csv -f table

Start the Web Dashboard

1. Run ./csvreport ui.
2. The server starts and automatically opens your standard web browser.
3. Upload a file and view the visual report.

The Web App

The Web App provides a user-friendly dashboard for managing your CSV analysis reports.

Running the Server

Run the ./csvreport ui command. On the first run, it will create a config.toml file in its directory.

Configuration (config.toml)

The config.toml file allows you to tune the server for your specific environment.

Server Settings

• port: The network port the server listens on (default: 5070).
• host: The IP address to bind to (use "0.0.0.0" to listen on all interfaces).
• max_upload_size_mb: Limits the size of uploaded CSV files.

Example:

[server]
port = 8080
host = "127.0.0.1"
max_upload_size_mb = 1024  # Allow up to 1GB uploads

CLI Settings

• executable_path: The path to the csvreport binary used for analysis (defaults to itself).
• timeout_seconds: How long to wait for the analysis to complete before timing out.

Example:

[cli]
executable_path = "./csvreport"
timeout_seconds = 300  # Give large files 5 minutes to process

Logging

• level: The verbosity of the server logs (error, warn, info, debug).

Example:

[logging]
level = "debug"

Storage Cleanup

Automatically remove old files to save disk space.

• enabled: Set to true to activate the cleanup task.
• interval_minutes: How often the cleanup task runs.
• retention_hours: Files older than this will be deleted.

Example:

[cleanup]
enabled = true
interval_minutes = 60    # Check every hour
retention_hours = 48     # Keep files for 2 days

The CLI Tool

The CLI tool is the engine of CSVREPORT, designed for performance and flexibility.

Basic Usage

./csvreport <PATH_TO_CSV> [OPTIONS]

Parameters & Examples

Output Formats (-f, --format)

Choose how the report should be presented. Available options: json (default), table, text.

Example: Table output (best for humans)

./csvreport my_data.csv -f table

Example: JSON output (best for scripts)

./csvreport my_data.csv -f json

Custom Delimiters (-d, --delimiter)

Force a specific separator. If omitted, the tool auto-detects between ,, ;, |, and \t.

Example: Semicolon separated file

./csvreport data.csv -d ";"

No Header Row (--no-header)

Use this flag if your CSV file starts directly with data and has no column names.

Example: Process raw data without headers

./csvreport raw_data.csv --no-header

Saving to a File (-o, --output)

Redirect the report output to a file instead of printing it to the terminal.

Example: Save a text summary

./csvreport huge_file.csv -f text -o summary.txt

About & Version

View build information and the software version.

./csvreport --about
./csvreport --version

Start Web UI (ui)

You can start the fully integrated graphical dashboard directly from the CLI.

./csvreport ui

You can also override the port:

./csvreport ui --port 8080

Sample CSV Data

If you want to test the tool, you can create a simple file named test.csv with the following content:

id,name,age,city,is_active
1,John Doe,28,New York,true
2,Jane Smith,34,London,true
3,Bob Wilson,,Berlin,false
4,Alice Brown,22,Paris,true
5,Charlie Davis,45,,

Running ./csvreport test.csv -f table will show you how the tool handles the missing values in the age, city, and is_active columns.

Report Properties

When the CSVREPORT analyzes a file, it generates a comprehensive JSON report containing detailed metadata and column-level statistics.

This page describes the structure of the generated report, which is especially useful if you are integrating the CLI tool’s JSON output into your own pipelines or reviewing the raw JSON in the Web App.

Root Properties (CsvReport)

The top-level object contains general information about the analyzed file and its structure.

Column Details (ColumnInfo)

The columns array contains an object for each column in the CSV file. This provides deep insights into data consistency, fill rates, and statistical metrics.

Example Output Snippet

{
  "file_path": "data/users.csv",
  "row_count": 3,
  "columns": [
    {
      "name": "age",
      "inferred_type": "Integer",
      "type_breakdown": null,
      "null_count": 1,
      "filled_count": 2,
      "fill_rate_pct": 66.66666666666666,
      "unique_value_count": 2,
      "leading_spaces_count": 0,
      "trailing_spaces_count": 0,
      "min_value": 25.0,
      "max_value": 30.0,
      "mean_value": 27.5,
      "min_length": 2,
      "max_length": 2
    }
  ]
}

Troubleshooting

Common issues and how to solve them.

Server won’t start

If you see an error like Address already in use, change the port in config.toml.

CLI error: “Executable not found”

Ensure the csvreport binary has executable permissions and is not blocked by your OS. The Web UI calls its own executable path for background analysis.

Analysis timeout

For extremely large files, increase the timeout_seconds in the [cli] section of config.toml.