Quickstart

Get Witan installed and exercising a workbook in under a minute. No signup or API key required for the personal tier.

1. Install

Install the standalone binary with the quick install script:

curl -fsSL https://witanlabs.com/install.sh | sh

This detects your platform and drops the witan binary into /usr/local/bin. For Windows, sandboxed environments, or manual binary downloads, see CLI page.

Alternatively, use npm or PyPI when those runtimes fit your environment better:

# npm one-shot
npx witan --help

# npm project install
npm install witan

# PyPI one-shot
uvx witan --help

# PyPI persistent install
pip install witan

The npm package includes the CLI and JavaScript SDK. The PyPI package includes the CLI and Python SDK.

2. Install the agent skills

If you use Witan through Claude Code, Codex, Deep Agents, or another skills-aware agent, install the Witan skills in your project:

npx skills add witanlabs/witan-cli

This adds the xlsx-code-mode and read-source skills so your agent knows the Witan commands, flags, and spreadsheet workflows before it starts touching workbooks. See Agent Skills for platform-specific notes.

3. Verify

witan --version

If you see a version string, you're ready.

4. Read a cell

Point Witan at any .xlsx file on disk:

witan xlsx exec report.xlsx --expr 'await xlsx.readCell(wb, "Summary!A1")'

The workbook is exposed inside the JavaScript runtime as the global wb. Methods on xlsx do the work. The result is returned as JSON.

5. Render a range

witan xlsx render report.xlsx -r "Sheet1!A1:Z50"

You'll get a PNG path printed to stdout, sized for vision models:

/var/folders/xx/.../witan-render-123456.png
Sheet1!A1:Z50 | ~3328x1500px | dpr=2

6. Recalculate

witan xlsx calc report.xlsx

Every formula in the workbook is recalculated, cached values are written back to disk, and any new errors are reported.

7. Lint

witan xlsx lint report.xlsx

Eleven rules check for the silent formula bugs recalculation cannot see — overlapping SUMs, unsorted lookups, mixed currencies, and more.

A more realistic example

The real power of exec is chaining operations into a single round-trip. Discover structure, look up a value by label, test a formula, write it, and verify — all in one call:

witan xlsx exec report.xlsx --save --code '
  const tables = await xlsx.detectTables(wb)
  const summary = tables.find(t => t.tableName === "Summary")

  const revenue = await xlsx.tableLookup(wb, {
    table: summary.address,
    rowLabel: "Total Revenue",
    columnLabel: "Q4"
  })

  const result = await xlsx.setCells(wb, [{
    address: revenue.address,
    formula: `=${revenue.address.replace("Q4","Q3")}*1.1`
  }])

  const lint = await xlsx.lint(wb, { rangeAddresses: [summary.address] })
  return { updated: revenue.address, errors: result.errors, warnings: lint.total }
'

The --save flag persists writes to the file on disk. Without it, exec is read-only by default — your script can experiment freely without modifying the workbook.

Next steps

Concepts — understand the workbook handle, sandbox runtime, and access tracking before you build more.
Skills — install the drop-in skills so Claude Code, Codex, and other agents know how to use Witan correctly.
CLI, render, calc, lint — full reference for each command.

Overview

Configuration