CLI Reference

The wb CLI reads, writes, and inspects .xlsx workbooks from the terminal.

In default mode, commands render human-readable text. Use --format json when you need structured output, or --mode agent to force JSON envelopes and structured help on stdout.

Installation

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

Usage

wb <command> [flags] <file>

Global Flags

Flag	Default	Description
--format <text|json|markdown|csv>	text	Output format. Most commands support text and json. read and calc also support markdown and csv; dep also supports markdown. Text output may omit columns that are entirely empty. Agent mode always forces json.
--mode <default|agent>	default	Output contract mode.
--compact	off	Emit compact JSON with no indentation.

Commands

info

Show sheet metadata including dimensions, cell counts, and formula presence.

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

Flags:

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

Example JSON 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 workbook. read returns stored or cached values; use calc to force formula recalculation.

wb read report.xlsx
wb read --sheet Sales --range A1:D10 report.xlsx
wb read --headers --format markdown report.xlsx
wb read --format csv --headers report.xlsx
wb read --include-formulas --include-styles report.xlsx
wb read --show-formulas report.xlsx
wb read --all-sheets --format markdown report.xlsx
wb read --headers --where "Status=Failed" report.xlsx
wb read --style-summary report.xlsx

Flags:

Flag	Default	Description
--sheet	first sheet	Sheet name to read
--all-sheets	false	Read all sheets. Mutually exclusive with --sheet
--range	full sheet	A1 range notation (e.g. A1:D10)
--limit	none	Limit output to the first N data rows
--head	none	Alias for --limit
--where	none	Filter rows with column=value style expressions; repeat for AND logic
--include-formulas	false	Include formula strings in output
--show-formulas	false	Show formula text instead of cached values for formula cells
--include-styles	false	Include style objects in output
--style-summary	false	Include a human-readable style summary per cell
--headers	false	Treat first row as column headers
--no-dates	false	Disable date detection and show raw numbers

Notes:

• --where supports =, !=, <, >, <=, and >=.
• With --headers, --where matches header names case-insensitively. Without --headers, it matches column letters such as A or B.
• Date cells are automatically detected and returned as type date with a formatted ISO 8601 string unless --no-dates is set.
• The markdown and csv formats output raw table data directly instead of a 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

# Validate, normalize, and return the operation plan
wb edit --format json --validate-only --plan --patch '[{"cell":"A1","clear":true}]' 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
--validate-only	false	Validate and apply in memory only; never saves
--atomic	true	Save only if all operations succeed
--no-atomic	false	Allow partial saves when operations fail
--plan	false	Include a normalized operation plan in the JSON output

Patch operations:

Each element in the patch array is a JSON object. All fields are optional except cell for cell and column operations, or row for row-height operations.

[
  {"cell": "A1", "value": "Hello"},
  {"cell": "B1", "value": 42},
  {"cell": "C1", "formula": "A1&B1"},
  {"cell": "A1", "style": {"font": {"bold": true}}},
  {"cell": "A1:C3", "clear": 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
clear	boolean	Clear cell contents or a full range

Notes:

• Patch JSON can be passed with --patch or via stdin.
• Setting cell values does not auto-expand formula ranges. If you add data beyond a range like SUM(B2:B3), update the formula separately.

---

create

Create a new workbook from a JSON spec. Unknown JSON fields are rejected.

# 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

# Row-oriented input
echo '{"rows":[{"start":"A1","data":[["Name","Score"],["Alice",10],["Bob",20]]}]}' | 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)"}
  ],
  "rows": [
    {"sheet": "Sheet2", "start": "A1", "data": [["Q1", "Q2"], [10, 20]]}
  ]
}

The cells array uses the same patch-operation format as edit.

---

calc

Force recalculation of all formulas and return evaluated 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
--no-dates	false	Disable date detection and show raw numbers

calc supports text, json, markdown, and csv. JSON output uses the same row structure as read, but always includes formula strings for formula cells.

---

dep

Show precedents and dependents for a single cell, a range, or every formula cell on a sheet.

wb dep report.xlsx
wb dep --sheet Sales report.xlsx
wb dep --cell D15 report.xlsx
wb dep --cell D15 --depth -1 report.xlsx
wb dep --direction dependents --cell D15 report.xlsx

Flags:

Flag	Default	Description
--cell	none	Show dependencies for a single cell
--range	none	Show dependencies for all formula cells in a range
--sheet	first sheet	Target sheet
--direction	both	Include precedents, dependents, or both
--depth	1	Transitive depth; use -1 for the full reachable graph

Notes:

• --cell and --range are mutually exclusive.
• When neither --cell nor --range is provided, wb discovers all formula cells on the target sheet.
• Dependents are searched across all sheets.

---

formula list

List all registered formula functions.

wb formula list

Use --format json when you want the registered function names as structured output.

---

help

Show help for the CLI or a specific command.

wb help
wb help read
wb help formula list
wb --mode agent help read

In default mode, help is human-readable text. With --format json or --mode agent, help is returned as structured JSON.

---

capabilities

Show structured CLI metadata for tooling and automation.

wb capabilities
wb capabilities --format json

This is the best entry point for discovering commands, supported formats, flags, and mode behavior without scraping prose help.

---

version

Print version information.

wb version

Output Modes

Default mode

Commands render human-readable text by default.

$ wb version
dev

JSON mode

Use --format json when you need a stable response envelope:

{
  "ok": true,
  "command": "read",
  "data": {
    "file": "report.xlsx",
    "sheet": "Sales",
    "range": "A1:D5",
    "rows": []
  },
  "meta": {
    "schema_version": "wb.v1",
    "tool_version": "dev",
    "mode": "default",
    "next_suggested_commands": [
      "wb calc <file>",
      "wb edit --patch '[...]' <file>"
    ]
  }
}

Useful top-level fields:

• ok
• command
• data
• error
• meta

Error hints live under error.hint, not as a top-level field.

In default mode, JSON errors are written to stderr:

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

Agent mode

--mode agent forces JSON envelopes to stdout for both success and error responses and returns structured help for wb help and <command> --help.

wb --mode agent help read
wb --mode agent capabilities

Exit Codes

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

Style JSON

Styles in edit patches and read --include-styles 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"