CLI: tabalyst scan
tabalyst scan INPUT... [OPTIONS]Describes CSV, JSON, JSONL or Excel (.xlsx, .xlsm) files in a JSON scan
document: every field, its presence, values, statistics and detected meanings.
Without -o or -d, the scan is stored in Tabalyst’s local storage, ready to be
reused by tabalyst report; with them, a standalone <stem>.scan.json is
written. The sources are never modified. See Scan CSV and JSON
files for what a scan analyzes.
Options
Section titled “Options”INPUT... is required: one or more files or non-recursive glob patterns. The
table at the end of this section shows which options each kind of file uses.
Options for every format
Section titled “Options for every format”| Option | Description |
|---|---|
-o, --output PATH | Scan filename ending in .json, for a single input. Not with -d |
-d, --output-dir PATH | Folder for standalone scans named <stem>.scan.json |
-c, --config PATH | JSON configuration file; repeat to merge several, in order |
-f, --force | Replace existing scan files |
-q, --quiet | Suppress success messages; warnings and errors remain |
-v, --verbose | Show the format, encoding, delimiter or table, status, diagnostics and duration |
--no-progress | Disable the progress line |
--no-html | Do not write the web page of the scan, <stem>.scan.html beside the scan document (beside the source when the scan is in the local storage). Refused with --plan |
--workers N | Worker processes that analyze values: 1 for one process. Files of 16 MiB or more use one per spare processor by default |
--counters | Add the work counters of the samplers to run.counters in the scan document (see Scan format). The scan always runs again |
--plan | Show the analyses a second pass could add, what they would cost and which the scan already answers, without running them. Uses the stored scan when it is current, otherwise makes it. Refuses -o, -d, --force and --counters. See Plan the analyses |
--stratify | With --plan, add the stratification advice: which columns make good strata for tabalyst sample, and how many strata each makes |
--stratify-by FIELDS | With --plan, assess the strata of several columns together, as a comma-separated list. Repeat it for other combinations. Implies --stratify |
--smart | With --plan, add the smart sample plan: the targets a smart sample would aim to cover, their weights, and the readings of the source it would take. With --deep, the second pass counts among them |
--sample-size N | With --stratify, --stratify-by or --smart, the number of rows the sample would hold |
--deep | Run the second pass: read each file again and add histograms, exact distinct counts and exact frequencies to deep.json, beside the scan. It asks first when it is costly. With --plan, show the second pass as if it were forced, with the estimated time and whether a run would ask. See Add histograms and exact medians |
-y, --yes | With --deep, start a costly second pass without asking. Outside a terminal, a costly second pass does not start without it |
--help | Show the options and exit |
Options for CSV files
Section titled “Options for CSV files”| Option | Description |
|---|---|
--delimiter TEXT | One-character delimiter, instead of the detected one |
--encoding TEXT | Text encoding, instead of the detected one |
Option for JSON and Excel files
Section titled “Option for JSON and Excel files”| Option | Description |
|---|---|
--collection TEXT | The part of the file to analyze. JSON: an array, such as data.items or '$.data.items[]'; . is the root array; repeatable, one dataset each. Excel: a sheet or table, such as Costs, Sales.Orders or '$["Q1 2026"]'; once. See Choosing a collection or a table |
A JSONL file has one dataset, its lines, so it has no collection to choose.
Options by format
Section titled “Options by format”| Option | CSV | JSON | JSONL | Excel |
|---|---|---|---|---|
-o, -d, -c, -f, -q, -v, --no-progress, --no-html, --workers, --counters, --plan, --stratify, --stratify-by, --smart, --sample-size, --deep | yes | yes | yes | yes |
--delimiter, --encoding | yes | - | - | - |
--collection | - | yes, repeatable | - | yes, once |
An option that a kind of file cannot use is ignored, with a warning, and the
scan is still made: scan sales.xlsx --delimiter ";" prints
Warning [sales.xlsx]: --delimiter is ignored: sales.xlsx is not a CSV file.
Examples
Section titled “Examples”CSV and JSON files
Section titled “CSV and JSON files”tabalyst scan customers.csvtabalyst scan data/*.csv -d scanstabalyst scan customers.csv -o scans/customers-2026.scan.json --forcetabalyst scan orders.jsonAdd histograms with a second pass
Section titled “Add histograms with a second pass”tabalyst scan customers.csv --deeptabalyst scan data/*.csv --deep --yestabalyst scan customers.csv --deep -o scans/customers.scan.jsonPlan the analyses
Section titled “Plan the analyses”tabalyst scan customers.csv --plantabalyst scan orders.json --collection customers --planChoosing a collection
Section titled “Choosing a collection”tabalyst scan orders.json --collection customerstabalyst scan orders.json --collection customers --collection productsWhen several arrays are equally plausible, scan stops with exit code 2 and
offers one command per array:
Choose the collection to analyze: tabalyst scan shop.json --collection customers tabalyst scan shop.json --collection ordersExcel workbooks
Section titled “Excel workbooks”tabalyst scan sales.xlsxtabalyst scan shop.xlsx --collection Coststabalyst scan shop.xlsx --collection '$["Sales Q1"]' -d scansA scan analyzes one table of a workbook. When several tables are equally
plausible, scan offers the same choices as report:
Choose the table to analyze: tabalyst scan shop.xlsx --collection Costs tabalyst scan shop.xlsx --collection '$["Sales Q1"]'To report every table of a workbook, use
tabalyst report --all-collections.
Reuse in a report
Section titled “Reuse in a report”tabalyst scan data/*.csv -d scanstabalyst report scans/*.scan.json --scan -d reportsExit codes
Section titled “Exit codes”| Code | When |
|---|---|
0 | Every scan was written |
1 | A scan could not be analyzed or written |
2 | Invalid options, or a JSON or Excel source whose collection or table must be chosen |
3 | With --deep, a confirmation was needed and not given: it could not be asked (not a terminal, no --yes) or the answer was no. Nothing was started |
4 | A source is missing, unreadable or invalid, or changed after its scan so that a second pass was discarded |