formualizer-cli

The formualizer command: recalculate the cached formula values in an .xlsx after another tool has edited it, preserving formula text, styles and the rest of the package. It is part of Formualizer, a Rust spreadsheet engine.

Install

cargo binstall formualizer-cli   # prebuilt binary from the GitHub release
cargo install formualizer-cli    # build from source

Both install a binary named formualizer. The same command also ships as a Python console script (uvx formualizer recalc book.xlsx), as the npm package @formualizer/cli (npx @formualizer/cli recalc book.xlsx) and as archives with SHA256SUMS on each GitHub release.

Usage

formualizer recalc <INPUT> [-o|--output <PATH>] [--check] [--json] [--max-errors <N>]
                   [--now <TIMESTAMP>] [--tz <ZONE>] [--seed <U64>]

$ formualizer recalc book.xlsx
book.xlsx: recalculated 5 formulas, 7 cached values changed, 1 error cells (Sheet1!B2 #DIV/0!) (written)

$ formualizer recalc book.xlsx --check
book.xlsx: recalculated 5 formulas, 0 cached values changed, 1 error cells (Sheet1!B2 #DIV/0!) (current)

$ formualizer recalc book.xlsx -o calculated.xlsx --json
{"schema":"formualizer.recalc/1","status":"written","input":"book.xlsx","output":"calculated.xlsx","written":true,"formula_cells":5,"cache_cells_changed":0,"worksheet_parts_changed":0,"error_cells":1,"errors":[{"sheet":"Sheet1","cell":"B2","error":"#DIV/0!"}],"errors_truncated":false,"refusal":null,"clock":{"now":"2026-10-04T09:15:02+02:00","timezone":"Local","fixed":false},"seed":17361606158148326741,"message":"book.xlsx: recalculated 5 formulas, 0 cached values changed, 1 error cells (Sheet1!B2 #DIV/0!) (written)"}

• Default: recalculate in place, atomically; a no-op leaves the file untouched. -o PATH always writes PATH and leaves the input alone.
• --check: compute only and report whether caches are current. Never writes.
• --json: one formualizer.recalc/1 object on stdout for every outcome, including refusals and usage errors.
• --max-errors N: list at most N error-cell locations (default 20).
• --now TIMESTAMP (RFC 3339 with an offset or Z), --tz UTC|±HH:MM, --seed U64: fix the TODAY/NOW clock and the RAND seed. RAND is reproducible by default; without --now, TODAY/NOW use host local time. With --now, reruns are byte-identical and --check is meaningful for volatile workbooks. JSON reports echo the clock and seed used, so any run can be replayed.

Formula results such as #DIV/0! are calculations, not command failures. Workbooks outside the supported subset (data tables, external links, hidden-row SUBTOTAL, circular references and others) are refused as a whole and nothing is written.

Exit codes

More

• Recalc CLI documentation: install, agent workflow, full reference and the supported/refused list.
• CLI reference on GitHub and eligibility contract.
• Embedding: formualizer_cli::run(args, stdout, stderr, cancel) returns the exit code without exiting the process or installing signal handlers. Disable default features to drop the SIGINT handler.

License

MIT OR Apache-2.0.