Skip to content
Beta · version 0.8.1 · commands and the JSON format may still change.

CLI: tabalyst report

Terminal window
tabalyst report INPUT... [OPTIONS]

Analyzes CSV, JSON, JSONL or Excel (.xlsx, .xlsm) files and writes, for each one, an interactive HTML report and a JSON profile, plus an executions.json history in the same folder. With --scan, the inputs are scan documents. The sources are never modified. See Tabalyst Report for what the report contains.

The report also adds, by itself, the exact analyses of a second pass that are useful and cheap: patterns counted on every value, dates by period, exact distinct counts and medians. It says so after the report path. See Second pass.

SourceReportProfile
CSV: data.csvdata.htmldata.json
JSON, JSONL, NDJSON or Excel: data.json, data.xlsxdata.report.htmldata.report.json
With --all-collections: shop.xlsxshop.<collection>.htmlshop.<collection>.json
With -o report.htmlreport.htmlreport.json

The files go beside the source, or in the folder of -d. .report keeps the profile of a JSON or Excel file from replacing a source with the same stem. With --details, the column pages and the chart pages are written in a folder named like the report, for example data/.

INPUT... is required: one or more files, scan documents with --scan, or non-recursive glob patterns. The table at the end of this section shows which options each kind of file uses.

OptionDescription
-o, --output PATHHTML filename ending in .html, for a single input. The profile takes the same name with .json. Not with -d or --all-collections
-d, --output-dir PATHFolder for the reports, named after their sources. Required by --all-collections with several inputs
-c, --config PATHJSON configuration file
-f, --forceReplace existing report files
--details, --no-detailsOne HTML page per column and the chart pages (off by default). Forces the second pass, as --deep: asks first when it is costly. An error when the configuration sets deep.mode to off
-q, --quietSuppress success messages; warnings and errors remain
-v, --verboseAlso show the profile and history paths, and the encoding and delimiter of a CSV file
--no-progressDisable the progress line
--workers NWorker processes that analyze values: 1 for one process. Files of 16 MiB or more use one per spare processor by default. Not with --scan
--deepForce the second pass: every applicable exact analysis, whatever the planner thinks of its cost. Asks first when it is costly
-y, --yesStart a costly forced second pass without asking. Outside a terminal, a costly forced second pass needs it
--dedup-report PATHA Dedup report (<name>.dedup.json), or the folder holding the one of each source. When it matches the scan, it proves how many rows are exact copies, so that the report can tell the repetitions of an identifier that copies explain from the others (identifier_uniqueness in the JSON profile). CSV sources only; a file serves a single source. Without it, the report beside each source (or beside the scan document with --scan) is tried. A path that does not exist, or a source that is not a CSV file, is an error
--helpShow the options and exit
OptionDescription
--delimiter TEXTOne-character delimiter, instead of the detected one
--encoding TEXTText encoding, instead of the detected one
OptionDescription
--collection TEXTThe part of the file to analyze. JSON: an array, such as data.items or '$.data.items[]'; . is the root array; repeatable. Excel: a sheet or table, such as Sales, Sales.Orders or '$["Q1 2026"]'; once. See Choosing a collection or a table. Not with --scan or --all-collections
--all-collectionsReport every visible collection of each file, as <name>.<collection>.html and .json. Not with -o, --collection or --scan

A JSONL file has one dataset, its lines, so it has no collection to choose.

OptionDescription
--scanBuild the reports from scan documents written by tabalyst scan, without reading the sources again, not even for the second pass unless --deep is given. Not with --delimiter, --encoding, --collection, --all-collections or --workers
OptionCSVJSONJSONLExcel
-o, -d, -c, -f, --details, -q, -v, --no-progress, --workers, --deep, --yesyesyesyesyes
--delimiter, --encodingyes---
--collection-yes, repeatable-yes, once
--all-collections-yes-yes
--scan (the inputs are scan documents)yesyesyesyes

An option that a kind of file cannot use is ignored, with a warning, and the report is still written: report sales.xlsx --delimiter ";" prints Warning [sales.xlsx]: --delimiter is ignored: sales.xlsx is not a CSV file.

Terminal window
tabalyst report customers.csv
tabalyst report data/*.csv -d reports
tabalyst report customers.csv -o out/customers-2026.html --details --force
tabalyst report semicolon.csv --delimiter ";" --encoding cp1252
Terminal window
tabalyst report sales.xlsx

When Tabalyst can tell which table to analyze, a workbook needs nothing else: only one table is eligible, or the largest has at least 10 times the rows of the next one. This writes sales.report.html, sales.report.json and executions.json.

When several tables are equally plausible, report analyzes nothing, exits with code 2 and offers the choices:

Terminal window
tabalyst report shop.xlsx
Error [shop.xlsx]: 2 tables of shop.xlsx are equally plausible. Nothing was analyzed.
Candidates:
$.Costs (40 rows)
$["Sales Q1"] (50 rows)
$.Notes (0 rows), empty
Pass --collection with a sheet or table path such as '$.Sheet', or run `tabalyst inspect shop.xlsx` and set config.structure.dataset_path in the file it writes.
Choose the table to analyze:
tabalyst report shop.xlsx --collection Costs
tabalyst report shop.xlsx --collection '$["Sales Q1"]'
Or report every table: tabalyst report shop.xlsx --all-collections

Copy the line you want and run it:

Terminal window
tabalyst report shop.xlsx --collection Costs
tabalyst report shop.xlsx --collection '$["Sales Q1"]'
tabalyst report shop.xlsx --collection Costs -d reports

The first one writes shop.report.html and shop.report.json. A named table of a sheet is chosen with --collection Sales.Orders.

Terminal window
tabalyst report shop.xlsx --all-collections
Report: shop.xlsx -> D:\work\shop.costs.html
Report: shop.xlsx -> D:\work\shop.sales-q1.html
2 succeeded, 0 failed

Each eligible table gets its own pair of files, named <file>.<collection-slug>: shop.costs.html, shop.costs.json, shop.sales-q1.html and shop.sales-q1.json. The slug is the sheet (and table) name in lower case, without accents, with every other character replaced by a hyphen, and a number is added when two names give the same slug. Only the visible sheets that Inspect finds eligible are reported: empty sheets and sheets without a header are left out, and a hidden sheet is left out with a warning (choose it with --collection).

A single file can go to a folder, and -d is required for several files:

Terminal window
tabalyst report shop.xlsx --all-collections -d reports
tabalyst report shop.xlsx orders.xlsx --all-collections -d reports
tabalyst report "exports/*.xlsx" --all-collections -d reports --force

A source with a single dataset, such as a CSV file, keeps its usual name in the same command. A workbook that has nothing to report fails alone, with exit code 2, and does not stop the others.

Terminal window
tabalyst report orders.json
tabalyst report shop.json --collection orders
tabalyst report shop.json --all-collections -d reports

For a JSON file with a customers and an orders array, the last command writes shop.customers.html and shop.orders.html with their .json profiles.

Terminal window
tabalyst scan data/*.csv -d scans
tabalyst report scans/*.scan.json --scan -d reports
Terminal window
tabalyst report customers.csv --config settings.json

The scan counts and samples everything in one pass. A second pass reads the file again for what a sample cannot give: the number of occurrences each inferred pattern reads in the whole file, the dates counted per day, month or year, the exact number of distinct values and the exact median of a column the scan stopped counting. tabalyst report decides by itself:

Terminal window
tabalyst report customers.csv
Analyzed 3,000 rows and 34 columns.
Report: D:\work\customers.html
Second pass (automatic): 36 analyses, 36 computed, 0 reused.

The planner picks an analysis only when it is useful and cheap, under budgets of memory and cells that do not depend on your machine, so the same file gives the same report anywhere. It never asks a question. The report says what was added, what the scan already answered and what was left out, in its Second pass section.

What you writeWhat happens
tabalyst report data.csvThe planner decides
tabalyst report data.csv --deepEvery applicable analysis the memory budget holds. Asks first when the estimate may reach two minutes or goes beyond what the planner chooses by itself; --yes skips the question; outside a terminal it stops with exit code 3 without --yes. With several files it asks once, with the total
tabalyst report data.csv -c off.json, with {"deep": {"mode": "off"}}No second pass: for a script that must read each file once. The report says the second pass is off
{"deep": {"mode": "force"}}The same as --deep on every run
tabalyst report scans/data.scan.json --scanThe source is not read. The analyses that the scan and the stored data.deep.json answer are in the report; the others are listed as skipped, with the reason
tabalyst report scans/data.scan.json --scan --deepThe source next to the scan document is read. If it is not there the command fails (exit code 4) and writes nothing
tabalyst report data.csv --detailsThe same as --deep, and the chart pages are written. With {"deep": {"mode": "off"}} it is an error: the charts need the second pass

The results are stored beside the scan, in deep.json, so that a second report of the same file, or one that changes only the presentation, reads nothing again. If the file changes while an automatic second pass runs, the report is still written without it, with a warning; a forced second pass fails instead. See Add histograms and exact medians with a second pass.

CodeWhen
0Every report was written
1A report could not be analyzed, rendered or written
2Invalid options, or a JSON or Excel source whose collection or table must be chosen
3A costly forced second pass (--deep or --details) needed a confirmation and was not given: no terminal and no --yes, or the answer was no. Nothing was started
4A source is missing, unreadable or invalid, or changed during a forced second pass

See also Report Excel workbooks, Report JSON files and Inspect.