microsheet

A terminal UI spreadsheet editor that operates directly on CSV files, with support for a small formula language. Built in Rust with ratatui and crossterm.

The CSV file is the source of truth: cells whose text starts with = are formulas, stored and round-tripped as plain text, and evaluated locally for display and for use by other formulas.

Features

• Spreadsheet-style grid navigation over CSV files, with A/B/C... column letters and 1-based row numbers always visible.
• In-place cell editing with a nano-style interface — no separate "insert" step; typing immediately edits the active cell.
• A small formula language: arithmetic, comparisons, string concatenation, cell references (A1) and ranges (A1:B3, whole-column B:B, whole-row 2:5), inter-sheet refs into sibling CSV files (other!A1, other!A1:B2), and a set of built-in functions (SUM, AVG, MIN, MAX, COUNT, COUNTA, IF, AND, OR, NOT, CONCAT, ROUND, ABS, LEN, UPPER, LOWER, TRIM).
• Automatic, dependency-aware recalculation on edit (including open-ended whole-row/column ranges as the sheet grows).
• Internal yank/cut/paste with range (visual) selection, including multi-cell block paste that grows the sheet as needed.
• Search and go-to-cell.
• In-app keybinding help overlay and per-column width adjustment.
• Saves back to CSV, preserving raw formula text and untouched literal cell text exactly.

Installation

Requires a recent stable Rust toolchain.

cargo install --git https://github.com/klay2000/microsheet

This installs the microsheet binary to ~/.cargo/bin (make sure that's on your PATH).

To build from a local checkout instead:

cargo install --path .

or just build without installing:

cargo build --release

which produces the binary at target/release/microsheet.

Usage

microsheet [OPTIONS] <FILE>

Option	Description
--delimiter <CHAR>	Field delimiter (default: ,)
--header	Treat the first row as column headers (shown as a pinned row below the A/B/C letters)

If <FILE> doesn't exist, microsheet opens an empty sheet at that path.

Keybindings

Navigation, editing, and saving follow a nano-style model: no mode switch is needed to start typing, and commands are Ctrl-prefixed shortcuts shown in the bottom bar (^O Write Out, ^X Exit, ^W Search, ^_ Go to cell, ^^ Toggle Mark, ^K/^U Cut/Paste, ^G Help overlay).

See MANUAL.md (§6) for the full keybinding reference, including edit mode and range-select mode.

Formula language

A formula is any cell whose text begins with =. References (A1, B2:D10) are case-insensitive and use absolute A1 addressing (no $ anchors). A reference may be qualified with a sheet name (other!A1) to read a sibling CSV file in the same directory — loaded once, read-only; missing files or out-of-bounds cells resolve to #REF!. Errors follow Excel-style conventions: #REF!, #VALUE!, #DIV0!, #NAME!, #CIRCULAR!, and a generic #ERR for malformed formulas.

See MANUAL.md (§7) for the full grammar, built-in function list, value/coercion rules, and error table.

Build / test / run

cargo build                # build
cargo test                 # run the test suite
cargo run -- <file.csv>    # run on a CSV file
cargo clippy -- -D warnings
cargo fmt

Project layout

src/
  main.rs          entry point, CLI args, terminal setup/teardown
  app.rs           App state, event loop, mode dispatch
  csv_io.rs        CSV load/save
  sheet.rs         Sheet/Cell data model
  formula/         lexer, parser, AST, evaluator, built-in functions, refs
  deps.rs          dependency graph + recalculation
  ui/              grid, formula bar, dialogs/help overlay
  clipboard.rs     internal yank/paste buffer

Documentation

• MANUAL.md — full user manual: UI layout, keybindings, formula language reference, CLI options, and error values.
• CLAUDE.md — development conventions for contributors.
• LICENSE — MIT license.

Cutting a release

Releases are built automatically by CI. To cut a new release:

1. Push a vX.Y.Z-form tag, e.g. git tag v1.1.0 && git push origin v1.1.0.
2. The Release GitHub Actions workflow (.github/workflows/release.yml) fires on the tag push, syncs Cargo.toml's version to the tag, runs cargo test, builds a .deb package and a Windows .exe (cross-compiled from Linux), and publishes a GitHub Release named after the tag with both artifacts attached and auto-generated release notes.