vgrid sheet

Sheet file operations for headless build, inspect, and verify workflows.

sheet apply

Build a .sheet file from a Lua script (replacement semantics).

vgrid sheet apply <output> --lua <script> [options]

Option	Description
--lua	Path to Lua build script (required)
--verify	Verify fingerprint after build (exit 1 if mismatch)
--stamp	Stamp file with expected fingerprint; optional label e.g. --stamp "MSFT SEC v1"
--dry-run	Compute fingerprint but don’t write file
--json	Output as JSON

The Lua script builds the sheet using these functions:

• set(cell, value) — set cell value or formula
• clear(cell) — clear cell
• meta(target, table) — semantic metadata (affects fingerprint)
• style(target, table) — presentation style (excluded from fingerprint)

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

# Build and verify fingerprint
vgrid sheet apply model.sheet --lua build.lua --verify v1:42:abc123...

# Dry run — compute fingerprint without writing
vgrid sheet apply model.sheet --lua build.lua --dry-run

# Build and stamp for GUI verification
vgrid sheet apply model.sheet --lua build.lua --stamp "Q4 Close v2"

sheet inspect

Inspect cells, ranges, or workbook metadata in a .sheet file.

vgrid sheet inspect <file> [target] [options]

Option	Description
--workbook	Show workbook metadata (fingerprint, sheet count)
--sheet	Select sheet by 0-based index or name (case-insensitive). Default: sheet 0
--sheets	List all sheets with dimensions and non-empty cell counts
--non-empty	Only include non-empty cells (sparse output — returns SparseInspectResult schema)
--include-style	Include style information
--headers	Treat first row as column headers (adds column_name to JSON/NDJSON output)
--format	Explicit format override: sheet, xlsx, csv, tsv (inferred from extension if omitted)
--delimiter	CSV field delimiter (single char or name: tab, comma, pipe, semicolon)
--calc <expr>	Evaluate formula against loaded data (repeatable). Output is always JSON. Exit 1 if any formula errors
--lightweight	Query SQLite directly without loading the full workbook. Skips formula recomputation and formatting. Only works with .sheet files. Ideal for server-side use
--json	Output as JSON
--ndjson	Output as newline-delimited JSON (one object per line, streamable)

# Inspect a cell
vgrid sheet inspect model.sheet A1

# Inspect a range
vgrid sheet inspect model.sheet A1:D10

# Workbook metadata
vgrid sheet inspect model.sheet --workbook

# JSON output with styles
vgrid sheet inspect model.sheet A1 --json --include-style

# List all sheets in a workbook
vgrid sheet inspect model.sheet --sheets --json

# Inspect a cell on a specific sheet (by index)
vgrid sheet inspect model.sheet --sheet 1 A1 --json

# Inspect a cell on a specific sheet (by name)
vgrid sheet inspect model.sheet --sheet Forecast B5 --json

# Sparse: all non-empty cells on a sheet
vgrid sheet inspect model.sheet --sheet Forecast --non-empty --json

# Sparse: non-empty cells within a range
vgrid sheet inspect model.sheet --sheet 1 A1:M100 --non-empty --json

# Streamable NDJSON output (one cell per line)
vgrid sheet inspect model.sheet --sheet Forecast --non-empty --ndjson

# Evaluate formulas against data (always JSON output)
vgrid sheet inspect data.csv --headers --calc "SUM(Amount)" --calc "SUM(Tax)"

# Inspect a CSV with explicit delimiter
vgrid sheet inspect data.tsv --format tsv --headers --json

Lightweight mode

--lightweight queries the .sheet file’s SQLite database directly, without loading cells into memory, rebuilding the dependency graph, or recomputing formulas. Formula cells return their last-saved cached values. This makes it safe for memory-constrained servers (e.g. 2 GB RAM) processing large workbooks.

# List sheets (SQL aggregates — no cell data loaded)
vgrid sheet inspect model.sheet --sheets --lightweight --json

# Preview first 100 rows (bounded SQL query)
vgrid sheet inspect model.sheet A1:Z101 --lightweight --json

# Workbook summary (sheet count + cell count only, no fingerprint)
vgrid sheet inspect model.sheet --lightweight --json

--lightweight cannot be combined with --calc, --include-style, or --value.

If --sheet references an invalid index or name, the error message lists available sheets.

Output schemas

Mode	Schema
--sheets	Array of SheetListEntry (index, name, non_empty_cells, max_row, max_col)
--non-empty	SparseInspectResult (sheet_index, sheet_name, range?, cells[])
Default cell/range	CellInspectResult / RangeInspectResult (unchanged)
--ndjson	One JSON object per line (same fields as --json, streamable)

--sheet is supported for .sheet and .xlsx only. --non-empty always returns SparseInspectResult schema. --ndjson emits one JSON object per line with no wrapper — suitable for streaming pipes and incremental agent processing.

sheet verify

Verify a .sheet file’s semantic fingerprint.

vgrid sheet verify <file> [options]

Option	Description
--fingerprint	Expected fingerprint (reads from file’s embedded fingerprint if not provided)

# Verify using embedded fingerprint
vgrid sheet verify model.sheet

# Verify against explicit fingerprint
vgrid sheet verify model.sheet --fingerprint v1:42:abc123

Exit code	Meaning
0	Verified (fingerprint matches)
1	Drifted (fingerprint mismatch) or Unverified (no expected fingerprint)
2	Usage error

sheet fingerprint

Compute and print a .sheet file’s fingerprint.

vgrid sheet fingerprint <file> [options]

Option	Description
--json	Output as JSON

vgrid sheet fingerprint model.sheet
vgrid sheet fingerprint model.sheet --json

sheet import

Import a foreign spreadsheet into canonical .sheet format.

vgrid sheet import <source> <output> [options]

Option	Description
--sheet	Sheet to import by index or name (XLSX only)
--headers	Treat first row as column headers
--formulas	Formula handling: values (default), keep, recalc
--nulls	Empty cell handling: empty (default), error
--stamp [label]	Stamp with provenance fingerprint + optional label
--verify	Verify fingerprint matches (exit 1 on mismatch)
--dry-run	Compute fingerprint without writing file
--json	Output structured JSON summary
--delimiter	CSV field delimiter

# Import CSV
vgrid sheet import data.csv data.sheet --headers

# Import XLSX with specific sheet
vgrid sheet import report.xlsx data.sheet --sheet Revenue

# Import and stamp for verification
vgrid sheet import data.csv data.sheet --headers --stamp "Q4 Filing"

# Dry run — compute fingerprint without writing
vgrid sheet import data.csv data.sheet --headers --dry-run --json

Tip

For a single-command flow that imports, verifies, and publishes to VisiHub, see vgrid pipeline publish.