Autoffice

A local-first command-line tool for automating Microsoft Excel (.xlsx) files. Reads a JSON mapping file, updates one or more cells across one or more worksheets, optionally applies formatting changes, and saves the result as a new workbook — without ever touching the original file.

Works on Linux x86_64, Linux ARM64, Raspberry Pi, Android Termux, Windows, and macOS. Pure Python runtime — no Rust, Cargo, or compiler required.

Install

pip install autoffice

Or download a pre-built binary from the Releases page (no Python required):

Android Termux

On Android Termux, install via pip (the pre-built Linux binary uses glibc and will not run on Termux's Bionic libc):

pkg install python
pip install autoffice

Debian / Ubuntu (.deb)

wget https://github.com/your-org/autoffice/releases/latest/download/autoffice_0.2.0_amd64.deb
sudo dpkg -i autoffice_0.2.0_amd64.deb

Usage

autoffice fill <workbook.xlsx> <mapping.json> [--force]

Example:

autoffice fill report.xlsx data.json

Writes report_filled.xlsx next to report.xlsx.

Use --force / -f to overwrite an existing output file.

Mapping file format

Each key uses <SheetName>!<CellReference> notation.

{
  "Sheet1!B19": {
    "value": "Hasan",
    "bold": true
  },
  "Sheet1!C19": {
    "value": 50000
  },
  "Summary!A1": {
    "value": "Completed",
    "italic": true,
    "font_size": 12
  }
}

Cell update fields

Only the fields you specify are changed — all other font attributes (name, colour, underline, etc.) are preserved as-is.

Logging

Set AUTOFFICE_LOG_LEVEL to enable verbose output:

# Show what cells are being updated
AUTOFFICE_LOG_LEVEL=INFO autoffice fill report.xlsx data.json

# Full debug trace (workbook open, each cell, save path)
AUTOFFICE_LOG_LEVEL=DEBUG autoffice fill report.xlsx data.json

Accepted values: DEBUG, INFO, WARNING (default), ERROR.

Validation

Validation runs before any writes. If validation fails:

• No cells are modified
• No output file is created
• Exit code 1 is returned
• A human-readable error message is printed

What is validated:

• Key format must be <SheetName>!<CellRef>
• Cell reference must be valid (A1, AA500, …)
• Every referenced worksheet must exist in the workbook
• font_size must be a positive number

Exit codes

Development

pip install -e ".[dev]"

# Run tests
pytest

# Lint & format
ruff check autoffice tests
ruff format autoffice tests

# Type-check
mypy autoffice

CI / CD

GitHub Actions runs automatically on every push and pull request:

1. Lint — ruff + mypy
2. Tests — pytest on Python 3.11, 3.12, and 3.13
3. Build — PyInstaller binaries for five platform targets
4. Deb — .deb packages for amd64 and arm64
5. Release — GitHub Release with all binaries and .deb files (triggered by v*.*.* tags)

To release a new version:

# Bump version in autoffice/__init__.py and pyproject.toml, then:
git tag v0.2.0
git push origin v0.2.0

Compatibility

Python versions: 3.11, 3.12, 3.13

Non-goals (v1)

• Formula evaluation
• .xls / .xlsm support
• YAML / CSV input
• Template engines
• Cloud services / COM automation
• GUI