CLI Reference

VisiGrid provides vgrid 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 | vgrid calc "=SUM(A:A)" --from csv

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

# Diff with one side from stdin
cat export.csv | vgrid diff - baseline.csv --key id

# Verify financial daily totals with signed proof
vgrid verify totals truth.csv warehouse.csv --sign --proof proof.json

# Validate a signed proof artifact
vgrid verify proof proof.json --check-files

# Export canonical truth seeds for dbt
vgrid export truth --transactions stripe_truth.csv --out seeds/

# Fetch transactions from Stripe API
vgrid fetch stripe --output transactions.csv

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

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

# Filter rows — no awk required
vgrid convert data.csv -t csv --headers --where 'Status=Pending'

# View a CSV file in the terminal
vgrid peek data.csv --headers

# View an Excel workbook
vgrid peek report.xlsx

# File shape without launching TUI
vgrid peek huge.csv --shape --headers

# List all 96+ supported functions
vgrid list-functions

# Fill a .sheet template with CSV data
vgrid fill model.sheet --csv data.csv --target tx!A1 --headers --out filled.sheet

# Publish to VisiHub
vgrid publish data.csv --repo acme/payments

# Build a .sheet from Lua script
vgrid sheet apply model.sheet --lua build.lua

---

Commands

Command	Description
calc	Evaluate a formula against stdin data
convert	Convert between file formats
diff	Reconcile two datasets by key
export	Export canonical truth data as dbt seeds
fetch	Fetch transactions from financial APIs
fill	Fill a .sheet template with CSV data
peek	View a file in the terminal
replay	Execute a Lua provenance script
sheet	Build, inspect, and verify .sheet files
publish	Authenticate and publish to VisiHub
verify	Verify financial totals with signed proofs
session	Control a running VisiGrid GUI
AI Agents	Agent workflow patterns

---

Small Utilities

list-functions

Print all supported spreadsheet functions.

vgrid list-functions

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

$ vgrid 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.

vgrid open [file]

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

ai doctor

Check AI configuration and connectivity.

vgrid ai doctor [options]

Option	Description
--json	Output as JSON for machine parsing
--test	Test provider connectivity (requires network)

# Check AI config
vgrid ai doctor

# Full connectivity test
vgrid ai doctor --test

# JSON output for scripting
vgrid ai doctor --json

---

Exit Codes

Code	Meaning
0	Success (for diff: reconciled — no missing rows, all diffs within tolerance)
1	Evaluation error or material diffs found (diff: missing rows or diffs outside tolerance; replay --verify: mismatch)
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)

diff exit-code semantics

Exit code 1 indicates material differences: missing rows or value diffs outside --tolerance. Within-tolerance diffs are reported in JSON output (with within_tolerance: true) but do not cause a non-zero exit code. This means --tolerance 0.01 in CI will pass when the only differences are rounding — no wrapper scripts needed.

The JSON summary includes both diff (total diff rows) and diff_outside_tolerance (material diffs only). The exit code is driven by diff_outside_tolerance.

stdout / stderr contract

• stdout is the data stream. Pipe it, redirect it, parse it.
• stderr is diagnostics. Error messages, warnings, summaries, skipped-row notes.
• Exit code is truth for pipelines. diff returns 0 when reconciled (no material diffs), 1 when material differences exist.
• --quiet suppresses stderr notes for both diff and convert. Use in pipelines and CI where only stdout and exit code matter.

---

Known Limitations (v0.5)

• XLSX export not yet implemented — use -t csv, -t tsv, or -t json
• calc reads from stdin only; no file-path argument
• replay: layout operations (sort, column widths, merge) are hashed for fingerprint but not applied to workbook data
• Nondeterminism detection is conservative — --verify fails if NOW(), TODAY(), RAND(), or RANDBETWEEN() appear anywhere in the script