CLI Reference

VisiGrid provides visigrid-cli for headless spreadsheet operations. Same engine as the desktop app, no GUI dependency. See Install to get set up.

Quick Examples

# Sum a column from CSV
cat sales.csv | visigrid-cli calc "=SUM(A:A)" --from csv

# Diff two datasets by key
visigrid-cli diff before.csv after.csv --key name

# Replay a provenance script and verify fingerprint
visigrid-cli replay audit-trail.lua --verify

# Convert XLSX to JSON
visigrid-cli convert data.xlsx -t json --headers

# List all 96+ supported functions
visigrid-cli list-functions

---

calc

Evaluate a spreadsheet formula against data from stdin or a file.

visigrid-cli calc <formula> --from <format> [options]

Option	Description
--from, -f	Input format: csv, tsv, json, lines, xlsx (required)
--headers	First row is headers (excluded from formulas)
--into	Load data starting at cell (default: A1)
--delimiter	CSV delimiter (default: ,)
--spill	Output format for array results: csv or json

Examples

# Sum a column
cat data.csv | visigrid-cli calc "=SUM(A:A)" --from csv

# Average with headers
echo -e "amount\n10\n20\n30" | visigrid-cli calc "=AVERAGE(A:A)" --from csv --headers

# Count lines in a file
cat file.txt | visigrid-cli calc "=COUNTA(A:A)" --from lines

# Conditional sum
cat sales.csv | visigrid-cli calc "=SUMIF(B:B, \">1000\", C:C)" --from csv

# Array formula with spill output
cat data.csv | visigrid-cli calc "=FILTER(A:A, B:B>10)" --from csv --spill json

Output rules

Result	Behavior
Scalar	Print raw value to stdout, exit 0
Error token	Print token (e.g., #DIV/0!) to stdout, diagnostic to stderr, exit 1
Array	Requires --spill. Without it, exit 1 with size hint.

Numbers print as raw values without locale formatting: 1234.5678 not $1,234.57.

---

diff

Reconcile two datasets by key column. Reports matched rows, rows only in left/right, and value differences with optional numeric tolerance.

visigrid-cli diff <left> <right> --key <column> [options]

Option	Description
--key	Key column — name, letter (A), or 1-indexed number (required)
--match	Matching mode: exact (default) or contains (substring)
--key_transform	Transform keys before matching: none, trim (default), digits
--compare	Columns to compare (comma-separated; omit for all non-key)
--tolerance	Numeric tolerance, absolute (default: 0)
--on_duplicate	Policy for duplicate keys: error (default)
--on_ambiguous	Policy for ambiguous matches (contains mode): error (default), report
--out	Output format: json (default) or csv
--output	Output file (default: stdout)
--summary	Summary destination: stderr (default), json, none
--no_headers	Treat first row as data (generate A, B, C headers)
--header_row	Header row number, 1-indexed
--delimiter	CSV delimiter (default: ,)

Examples

# Basic diff by name column
visigrid-cli diff q3.csv q4.csv --key name

# With numeric tolerance (e.g., rounding differences)
visigrid-cli diff expected.csv actual.csv --key sku --tolerance 0.01

# Substring matching (left key contained in right key)
visigrid-cli diff short_codes.csv full_names.csv --key id --match contains --on_ambiguous report

# Compare specific columns only
visigrid-cli diff before.csv after.csv --key id --compare "price,quantity"

# CSV output to file
visigrid-cli diff left.csv right.csv --key name --out csv --output result.csv

JSON output structure

{
  "summary": {
    "left_rows": 50,
    "right_rows": 48,
    "matched": 45,
    "only_left": 5,
    "only_right": 3,
    "diff": 12,
    "tolerance": 0.01,
    "key": "name",
    "match": "exact",
    "key_transform": "trim"
  },
  "results": [
    {
      "status": "matched",
      "key": "Alice",
      "diffs": null
    },
    {
      "status": "diff",
      "key": "Bob",
      "diffs": [
        { "column": "amount", "left": "1200", "right": "1350", "delta": 150.0, "within_tolerance": false }
      ]
    },
    {
      "status": "only_left",
      "key": "Carol"
    }
  ]
}

Key transforms

Transform	Behavior
none	Compare keys as-is
trim	Strip leading/trailing whitespace (default)
digits	Extract only digits from keys

Numeric tolerance

When --tolerance is set, numeric values are compared with absolute tolerance. Financial formats are parsed automatically ($1,234.56, parenthesized negatives like (500)). The within_tolerance field in output indicates whether a delta falls within the threshold.

---

replay

Execute a Lua provenance script and optionally verify the output fingerprint.

visigrid-cli replay <script> [options]

Option	Description
--verify	Verify fingerprint against script header (fail if mismatch)
--output, -o	Output file for resulting spreadsheet
--format, -f	Output format (inferred from extension if omitted)
--fingerprint	Print fingerprint and exit
--quiet, -q	Only print errors

Examples

# Replay and verify fingerprint matches
visigrid-cli replay audit-trail.lua --verify

# Replay and export result as CSV
visigrid-cli replay changes.lua --output snapshot.csv

# Just compute the fingerprint
visigrid-cli replay changes.lua --fingerprint

# Quiet mode for CI
visigrid-cli replay changes.lua --verify --quiet

Provenance scripts

Every edit in VisiGrid can generate a Lua provenance script — a complete, ordered record of what changed. These scripts are plain text and version-control friendly.

-- VisiGrid provenance script
-- Generated: 2025-01-15T09:42:00Z
-- Fingerprint: v1:6:a3f8c2d1

sheet:set("A1", "Revenue")
sheet:set("A2", 42850)
sheet:set("A3", 38100)
sheet:set("B1", "Total")
sheet:set("B2", "=SUM(A2:A3)")

Fingerprint format

Fingerprints use the format v1:<length>:<hash>. The hash is computed from the final spreadsheet state. Scripts containing nondeterministic functions (NOW, TODAY, RAND, RANDBETWEEN) cannot be verified — --verify will fail with an error.

Verification

$ visigrid-cli replay audit-trail.lua --verify
Replayed 12 operations
Fingerprint: v1:6:a3f8c2d1
Verification: PASS (matches expected)

If the source data or the script has been modified, verification fails with a non-zero exit code.

---

convert

Convert between file formats.

visigrid-cli convert [input] -t <format> [options]

Option	Description
--from, -f	Input format (required when reading from stdin)
--to, -t	Output format: csv, tsv, json, lines (required)
--output, -o	Output file (default: stdout)
--sheet	Sheet name for multi-sheet files (default: first)
--delimiter	CSV/TSV delimiter (default: , for csv, \t for tsv)
--headers	First row is headers (affects JSON object keys)

Examples

# XLSX to JSON with headers as keys
visigrid-cli convert data.xlsx -t json --headers

# CSV to JSON via stdin
cat data.csv | visigrid-cli convert -f csv -t json

# JSON to CSV
curl -s api.example.com/data | visigrid-cli convert -f json -t csv

# Select a specific sheet from XLSX
visigrid-cli convert report.xlsx -t csv --sheet "Q4 Data"

# File to file
visigrid-cli convert data.xlsx -t csv -o data.csv

Format support

Format	Extensions	Read	Write
csv	.csv	yes	yes
tsv	.tsv	yes	yes
json	.json	yes	yes
lines	—	yes	yes
xlsx	.xlsx, .xls	yes	—
sheet	.sheet	yes	yes

When reading from a file, the format is inferred from the extension. Use --from to override or when reading from stdin.

---

list-functions

Print all supported spreadsheet functions.

visigrid-cli list-functions

Outputs one function name per line, sorted alphabetically. Suitable for grep and wc -l.

$ visigrid-cli list-functions | head -5
ABS
ACOS
AND
AVERAGE
AVERAGEIF

96+ functions are supported — the same engine that powers the desktop app.

---

open

Launch the desktop GUI, optionally opening a file.

visigrid-cli open [file]

Looks for VisiGrid.app on macOS or visigrid-gui in PATH on Linux/Windows.

---

Exit Codes

Code	Meaning
0	Success
1	Evaluation error (formula error, spill without --spill)
2	Invalid arguments
3	I/O error (also: duplicate keys in diff)
4	Parse error (malformed input; also: ambiguous matches in diff)
5	Format error (unsupported format; also: diff parse error)

stdout / stderr contract

• stdout is the data stream. Pipe it, redirect it, parse it.
• stderr is diagnostics. Error messages, warnings, summaries.
• Exit code is truth for pipelines. Non-zero on any error.