Repo del giorno: OfficeCLI, la suite Office nata per gli agenti AI

🔍 Cos'è OfficeCLI

OfficeCLI è uno strumento da riga di comando che legge, crea e modifica file Word (`.docx`), Excel (`.xlsx`) e PowerPoint (`.pptx`) senza bisogno di Microsoft Office, di LibreOffice o di runtime esterni: è un binario self-contained scritto in C# (il runtime .NET è incorporato nel binario, non va installato) disponibile per macOS, Linux e Windows, anche via Homebrew, Scoop o npm.

La differenza rispetto alle librerie classiche come python-docx o openpyxl non è solo la comodità: è il disegno. Ogni elemento del documento ha un path stabile (`/slide[1]/shape[2]`, `/body/p[5]`), ogni comando supporta `--json` con schemi coerenti, e gli errori tornano con codice, suggerimento e range validi, così l'agente si auto-corregge senza intervento umano. Quello che con tre librerie Python richiedeva cinquanta righe, qui è un comando.

repo       iOfficeAI/OfficeCLI
cosa       suite Office per agenti AI: crea/legge/modifica docx, xlsx, pptx
come       binario singolo C#/.NET · niente Office · macOS, Linux, Windows
chicca     rendering HTML/PNG integrato: l'agente vede ciò che produce
extra      motore formule Excel (350+ funzioni), template merge, MCP server
licenza    Apache 2.0 · ~24.500 stelle · release frequenti

⚙️ Installazione e primi comandi

L'installazione è un comando, e c'è persino una scorciatoia pensata per gli agenti: si incolla nella chat dell'agente l'URL dello SKILL.md e ci pensa lui a installare il binario e imparare i comandi. Per gli umani ci sono lo script di install, Homebrew (`brew install officecli`) o npm; il comando `officecli install` copia il binario nel PATH e installa la skill in tutti gli agenti di coding che rileva — Claude Code, Cursor, GitHub Copilot e altri.

I comandi seguono un pattern uniforme su tutti e tre i formati: `create` per il file vuoto, `add`/`set`/`remove`/`move` per gli elementi, `view` per le viste ad alto livello (outline, testo, statistiche, problemi), `get`/`query` per interrogare con selettori CSS-like. Con `watch` si apre un'anteprima live nel browser che si aggiorna a ogni modifica: un feedback loop immediato anche per chi sta solo sperimentando.

# Installazione (macOS / Linux) — oppure: brew install officecli
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

# Crea una presentazione e aggiungi contenuto
officecli create deck.pptx
officecli add deck.pptx / --type slide --prop title="Q4 Report"

# Anteprima live nel browser (si aggiorna a ogni modifica)
officecli watch deck.pptx   # http://localhost:26315

# Interroga la struttura in JSON
officecli get deck.pptx '/slide[1]' --json

🧭 Tre livelli di accesso: dal semplice al raw XML

L'architettura è a tre livelli progressivi, pensata per minimizzare i token che un agente consuma. Il livello L1 offre viste semantiche in sola lettura (`view` con modalità outline, text, annotated, stats, issues); il livello L2 lavora sul DOM del documento con operazioni strutturate (`get`, `query`, `set`, `add`, `remove`, `move`, `swap`); il livello L3 è la valvola di sfogo universale: accesso XPath diretto al raw XML OOXML per i casi che il DOM non copre.

In pratica l'agente parte leggero, scala di livello solo quando serve, e non resta mai bloccato: se una proprietà non è esposta, c'è sempre `raw-set`. Completano il quadro la modalità resident (documento tenuto in memoria fra un comando e l'altro, latenza quasi nulla via named pipe) e il batch atomico: più operazioni in un colpo solo, e se una fallisce l'intero batch fa rollback.

👁️ Il motore di rendering: dare occhi all'agente

Il pezzo che considero il cuore del progetto è il motore di rendering HTML scritto da zero e incorporato nel binario. Tre modalità: `view html` produce un file HTML standalone con gli asset inline, `view screenshot` genera un PNG per pagina pronto per un modello multimodale, `watch` serve l'anteprima auto-aggiornante. Copre forme, grafici (trendline, waterfall, candlestick), equazioni (OMML reso con KaTeX), perfino modelli 3D e transizioni morph.

Perché è così importante? Senza visualizzazione, un agente che genera slide può leggere il DOM ma non può accorgersi che il titolo sborda o che due forme si sovrappongono. Con il rendering dentro il binario, il loop render → guarda → correggi funziona ovunque giri il binario: in CI, in Docker, su un server senza display. È la stessa filosofia dei tool di browser-testing per il vibe coding, applicata ai documenti.

# Renderizza la slide in PNG: l'agente (multimodale) la guarda
officecli view deck.pptx screenshot -o /tmp/deck.png

# Enumera i problemi rilevati (testo che sborda, alt text mancanti...)
officecli view deck.pptx issues --json

# Corregge e valida contro lo schema OpenXML
officecli set deck.pptx '/slide[1]/shape[1]' --prop size=24
officecli validate deck.pptx

🔌 Skill, MCP e motore formule: l'integrazione con gli agenti

L'integrazione con gli agenti è a doppio binario. La via CLI: `officecli install` rileva gli strumenti AI presenti sulla macchina e installa lo SKILL.md nelle rispettive configurazioni, così l'agente sa già usare tutti i comandi. La via MCP: `officecli mcp claude` (o `cursor`, `vscode`, `lmstudio`) registra il server MCP integrato, che espone le operazioni sui documenti come tool JSON-RPC — utile quando l'agente non ha accesso alla shell.

Sotto il cofano ci sono due motori che evitano il round-trip con Office: un motore formule Excel con oltre 350 funzioni valutate automaticamente alla scrittura (comprese le dynamic array come FILTER e SORT, le famiglie finanziarie e statistiche) e le pivot table native OOXML create con un comando. E per la produzione ripetitiva c'è `merge`: l'agente disegna il layout una volta, il codice a valle riempie i segnaposto `{{key}}` N volte, deterministico e a costo zero di token. Con `dump` si fa il percorso inverso: un documento esistente diventa un blueprint JSON rigiocabile con `batch`.

🏢 Perché è interessante, per sviluppatori e PMI

Per chi sviluppa, OfficeCLI trasforma l'automazione Office da palude di librerie a pipeline pulita: generazione report da database in CI/CD, batch di find/replace su centinaia di documenti, validazione di qualità prima della consegna — tutto scriptabile da qualsiasi linguaggio, perché è una CLI, con SDK sottili per Python e Node.js se si preferisce il resident mode. E per chi lavora in .NET c'è un motivo di interesse in più: il progetto dimostra cosa si può fare con un binario nativo self-contained compilato da C#.

Per una PMI il punto è un altro: i documenti Office sono il formato in cui l'azienda vive — offerte, report, listini, presentazioni. Dare a un agente la capacità di leggerli e produrli in modo affidabile, con un controllo qualità automatico prima della consegna, apre automazioni concrete senza licenze aggiuntive: il tool è gratuito, open source e gira anche su un server headless. La domanda «l'agente può preparami il report settimanale in Word partendo dai dati?» con questo tassello ha una risposta tecnica seria.

⚠️ Limiti e cautele prima di adottarlo

Come sempre, qualche cautela. Il progetto è giovane e in evoluzione rapidissima: le release sono frequenti e le superfici possono cambiare, quindi in una pipeline di produzione conviene bloccare la versione del binario (l'auto-update si disattiva con `officecli config autoUpdate false`). La fedeltà del rendering è alta ma non è Office: per documenti con layout estremi il controllo finale in PowerPoint o Word resta prudente.

Attenzione anche al pattern di installazione via `curl | bash` e all'auto-install delle skill negli agenti rilevati: in un contesto aziendale è più pulito scaricare il binario dalle release GitHub, verificarlo e distribuirlo in modo controllato. Infine, i file `.doc` legacy e l'export PDF passano da plugin dedicati, non dal core.

• Progetto giovane: release frequenti, superfici in evoluzione; in produzione bloccare la versione del binario.
• Rendering fedele ma non identico a Office: per layout critici serve comunque un controllo finale.
• Auto-install invasivo per gusto enterprise: rileva e configura gli agenti da solo; in azienda meglio una distribuzione controllata.
• Formati legacy via plugin: `.doc`, `.hwpx` ed export PDF non sono nel core.
• Flush su disco in resident mode: prima che un altro programma legga il file va dato `save` o `close`, dettaglio documentato ma da conoscere.

✅ Da dove partire

Il percorso che suggerisco è in tre passi. Primo: installare il binario e provare il giro `create` → `add` → `watch` su un pptx di prova, per toccare con mano l'anteprima live. Secondo: agganciarlo al proprio agente — la via più rapida è incollare l'URL dello SKILL.md nella chat, la più pulita è `officecli mcp claude` — e chiedergli di generare un documento reale, guardando come usa `view issues` per auto-correggersi. Terzo: per un caso d'uso ripetitivo, investire sul pattern `merge`: layout disegnato una volta, dati riempiti N volte.

Il segnale più ampio è che l'ecosistema degli agenti sta colmando una alla volta le lacune di percezione: prima il browser, ora i documenti Office. Un agente che vede ciò che produce sbaglia meno, e un formato vecchio di trent'anni come OOXML diventa improvvisamente un terreno dove l'automazione seria è a portata di CLI.