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)
{"op": "set", "cell": "A1", "value": "Hello"}
{"op": "set", "cell": "B1", "formula": "=A1 & \" World\""}

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