CLI Reference

The wb CLI reads, writes, and manipulates Excel files from the terminal.

Installation

go install github.com/jpoz/werkbook/cmd/wb@latest

Global Flags

Flag	Default	Description
`--format`	`json`	Output format: `json`, `markdown`, or `csv`

Commands

info

Show sheet metadata — dimensions, cell counts, and data ranges.

wb info report.xlsx
wb info --sheet Sales report.xlsx

Flags:

Flag	Default	Description
`--sheet`	all sheets	Filter to a specific sheet

Example output:

{
  "ok": true,
  "command": "info",
  "data": {
    "file": "report.xlsx",
    "sheets": [
      {
        "name": "Sales",
        "max_row": 100,
        "max_col": 5,
        "max_col_letter": "E",
        "non_empty_cells": 450,
        "has_formulas": true,
        "data_range": "A1:E100"
      }
    ]
  }
}

read

Read cell data from a sheet.

wb read report.xlsx
wb read --sheet Sales --range A1:D10 report.xlsx
wb read --headers --format markdown report.xlsx
wb read --include-formulas --include-styles report.xlsx

Flags:

Flag	Default	Description
`--sheet`	first sheet	Sheet name to read
`--range`	full sheet	A1 range notation (e.g. `A1:D10`)
`--include-formulas`	`false`	Include formula strings in output
`--include-styles`	`false`	Include style objects in output
`--headers`	`false`	Treat first row as column headers

The markdown and csv formats output raw table data directly (no JSON envelope).

edit

Apply changes to an existing workbook using a JSON patch array.

# Patch from flag
wb edit --patch '[{"cell":"A1","value":"Updated"}]' report.xlsx

# Patch from stdin
cat patch.json | wb edit report.xlsx

# Save to a different file
wb edit --output new.xlsx --patch '[{"cell":"A1","value":"Hello"}]' report.xlsx

# Preview changes without saving
wb edit --dry-run --patch '[{"cell":"A1","value":"Test"}]' report.xlsx

Flags:

Flag	Default	Description
`--sheet`	first sheet	Default sheet for operations
`--patch`	stdin	JSON array of patch operations
`--output`	overwrite input	Save to a different file path
`--dry-run`	`false`	Apply in memory without saving

Patch operations:

Each element in the patch array is a JSON object. All fields are optional except cell (or row for row operations).

[
  {"cell": "A1", "value": "Hello"},
  {"cell": "B1", "value": 42},
  {"cell": "C1", "formula": "A1&B1"},
  {"cell": "A1", "style": {"font": {"bold": true}}},
  {"cell": "A", "column_width": 20.0},
  {"row": 1, "row_height": 30.0},
  {"add_sheet": "NewSheet"},
  {"delete_sheet": "OldSheet"}
]

Field	Type	Description
`cell`	string	Cell reference (`"A1"`), column letter (`"B"`), or range (`"A1:D1"`)
`row`	int	Row number (for `row_height`)
`sheet`	string	Target sheet (defaults to `--sheet` flag)
`value`	any	Cell value (`null` clears the cell)
`formula`	string	Formula string (e.g. `"SUM(B2:B3)"`)
`style`	object	Style object (see below)
`column_width`	number	Column width (use `cell` as column letter)
`row_height`	number	Row height (use `row` as row number)
`add_sheet`	string	Create a new sheet
`delete_sheet`	string	Delete a sheet

create

Create a new workbook from a JSON spec.

# Spec from flag
wb create --spec '{"sheets":["Data"],"cells":[{"cell":"A1","value":"Hello"}]}' out.xlsx

# Spec from stdin
cat spec.json | wb create out.xlsx

Flags:

Flag	Default	Description
`--spec`	stdin	JSON spec for the new workbook

Spec format:

{
  "sheets": ["Sheet1", "Sheet2"],
  "cells": [
    {"cell": "A1", "sheet": "Sheet1", "value": "Name"},
    {"cell": "B1", "sheet": "Sheet1", "formula": "SUM(B2:B10)"}
  ]
}

The cells array uses the same format as edit patch operations.

calc

Force-recalculate all formulas and return the results.

wb calc report.xlsx
wb calc --range A1:D10 report.xlsx
wb calc --output recalculated.xlsx report.xlsx

Flags:

Flag	Default	Description
`--sheet`	first sheet	Sheet to read results from
`--range`	full sheet	A1 range to return
`--output`	don’t save	Save recalculated workbook to this path

Output uses the same format as read, but always includes formula strings.

formula list

List all registered formula functions.

wb formula list

Example output:

{
  "ok": true,
  "command": "formula",
  "data": {
    "functions": ["ABS", "AND", "AVERAGE", "..."],
    "count": 55
  }
}

version

Print version information.

wb version

Output Format

All JSON output uses a consistent envelope:

{
  "ok": true,
  "command": "read",
  "data": { ... }
}

Errors are written to stderr:

{
  "ok": false,
  "command": "read",
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "file does not exist",
    "hint": "check the file path"
  }
}

Exit Codes

Code	Meaning
0	Success
1	File I/O error
2	Validation error
3	Partial failure (some operations succeeded)
4	Usage/argument error

Style JSON

Styles in edit and read output use this structure:

{
  "font": {
    "name": "Calibri",
    "size": 11,
    "bold": true,
    "italic": false,
    "underline": false,
    "color": "FF0000"
  },
  "fill": {"color": "FFFF00"},
  "border": {
    "top": {"style": "thin", "color": "000000"},
    "bottom": {"style": "medium", "color": "000000"},
    "left": {"style": "thin", "color": "000000"},
    "right": {"style": "thin", "color": "000000"}
  },
  "alignment": {
    "horizontal": "center",
    "vertical": "top",
    "wrap_text": true
  },
  "num_fmt": "#,##0.00"
}

Border styles: "thin", "medium", "thick", "dashed", "dotted", "double"