Session Commands

Control a running VisiGrid GUI from the terminal. Inspect cells, apply changes, and watch state evolve — all from scripts or the command line.

The session server runs on TCP localhost with token auth. Protocol v1 is frozen — wire format locked by golden vectors.

sessions

List running VisiGrid sessions.

vgrid sessions [options]

Option	Description
`--json`	Output as JSON array

# List all sessions
vgrid sessions

# Get session ID for scripting
SESSION=$(vgrid sessions --json | jq -r '.[0].session_id')

attach

Attach to a session (interactive mode). Useful for debugging and exploration.

vgrid attach [options]

Option	Description
`--session`	Session ID (auto-discovers if only one)

inspect

Inspect cells, ranges, or workbook metadata from a running session.

vgrid inspect <target> [options]

Option	Description
`--session`	Session ID
`--sheet`	Sheet index, 0-based (default: `0`)
`--json`	Output as JSON

Targets:

A1 — single cell (value, formula, format)
A1:D10 — range (values only)
workbook — revision, sheet count, dirty state

# Inspect a cell
vgrid inspect A1
# -> A1 = 1234.56  (number)

# Inspect a range on sheet 1
vgrid inspect A1:B10 --sheet 1

# Get workbook revision for conditional apply
REV=$(vgrid inspect workbook --json | jq '.revision')

apply

Apply operations to a running session. Reads JSON Lines from stdin or file.

vgrid apply <file> [options]

Option	Description
`--session`	Session ID
`--atomic`	All-or-nothing apply (rollback on any failure)
`--expected-revision`	Fail if current revision doesn’t match
`--wait`	Retry on conflict (requires `--atomic` or `--expected-revision`)
`--wait-timeout`	Max wait time in seconds (default: `30`)

Safety: --wait requires either --atomic or --expected-revision to prevent unbounded retries without idempotency protection.

# Apply operations atomically
cat ops.jsonl | vgrid apply -

# Conditional apply with revision check
vgrid apply ops.jsonl --atomic --expected-revision $REV --wait

# Custom timeout
vgrid apply ops.jsonl --atomic --wait --wait-timeout 60

# Operation format (JSON Lines) — coordinates are 0-based; `sheet` defaults to 0
{"op": "set_cell_value", "row": 0, "col": 0, "value": "Hello"}
{"op": "set_cell_formula", "row": 0, "col": 1, "formula": "=A1 & \" World\""}
{"op": "clear_cell", "row": 1, "col": 0}
{"op": "set_number_format", "start_row": 0, "start_col": 2, "end_row": 9, "end_col": 2, "format": "currency:2"}
{"op": "set_style", "start_row": 0, "start_col": 0, "end_row": 0, "end_col": 9, "bold": true}

Range ops (set_number_format, set_style) apply from VisiGrid v0.14. Number formats accept named forms (general, number[:decimals], currency[:decimals], percent[:decimals], date, time, datetime) or a raw Excel format code like "#,##0.00".

Every op in a batch is validated against the grid bounds and sheet list before anything is applied — an invalid op rejects the whole batch with a structured error (out_of_bounds, sheet_not_found, invalid_op, cells_limit_exceeded) naming the offending op index.

The --wait flag enables adaptive retry with exponential backoff and jitter. The server may return retry_after_ms hints which the client respects.

stats

Query server health and metrics.

vgrid stats [options]

Option	Description
`--session`	Session ID
`--json`	Output as JSON

vgrid stats
# -> uptime: 3h 42m | connections: 2 | ops: 1,247 | revision: 89

view

View a read-only snapshot of the grid from a running session.

vgrid view [options]

Option	Description
`--session`	Session ID
`--range`	Range to display (default: `A1:J20`)
`--sheet`	Sheet index, 0-based (default: `0`)
`--width`	Column width for display (default: `12`)
`--follow`	Follow mode: refresh on changes (poll every 500ms)

# View current grid state
vgrid view

# View specific range
vgrid view --range A1:D10

# View a different sheet with wider columns
vgrid view --sheet 1 --width 20

# Watch for changes in real time
vgrid view --follow

Output is an ASCII table with column headers and row numbers. Wide values are truncated with ...

Exit codes

Code	Meaning
20	Cannot connect (no server, connection refused)
21	Protocol error (version mismatch, malformed message)
22	Authentication failed
23	Write conflict or revision mismatch
24	Partial apply (non-atomic had rejections)
25	Invalid input (bad op schema)
26	Operation timed out

Scripting example

# Get session
SESSION=$(vgrid sessions --json | jq -r '.[0].session_id')

# Inspect current state
REV=$(vgrid inspect workbook --json | jq '.revision')

# Apply changes with revision check
vgrid apply ops.jsonl --atomic --expected-revision $REV --wait

# Verify new state
vgrid view --range A1:D10