Guía de OfficeCLI

1. Introducción

OfficeCLI es una herramienta de línea de comandos diseñada para que agentes de IA puedan crear, leer y modificar documentos de Office (Word, Excel y PowerPoint) sin necesidad de tener Microsoft Office instalado. Es un binario único, open source y multiplataforma.

Característica	Descripción
Sin dependencias	Binario único, no necesita Office ni Python
JSON estructurado	Salida predecible para agentes (`--json`)
Paths estables	Cada elemento tiene una ruta como `/slide[1]/shape[2]`
Renderizado HTML	Previsualización en navegador sin Office
Skills/MCP server	Integración directa con agentes (Claude Code, OpenCode, Cursor...)

2. Instalación

Lo primero, selecciona tu sistema operativo:

En Linux, instala con un solo comando. Si tienes Windows con WSL, también sirve este comando:

curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

En Windows (PowerShell):

irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

En macOS, puedes usar Homebrew:

brew install officecli

O con el script de instalación:

curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

Con npm (funciona en todas las plataformas):

npm install -g @officecli/officecli

Una vez instalado, verifica que está correctamente instalado. Si te devuelve el número de versión, todo ha ido correctamente (a veces puedes necesitar reiniciar la terminal):

officecli --version

3. Conceptos clave

Este apartado sólo habla de detalles técnicos por si tienes curiosidad de como funciona officecli. Si sólo te interesa hacerlo funcionar, puedes saltarte este apartado y pasar al siguiente.

OfficeCLI funciona en 3 capas: empieza leyendo, luego edita elementos concretos, y si necesitas control total, accede al XML directamente.

L1 (lectura): view para obtener texto, esquema o HTML del documento.
L2 (DOM): get, set, add, remove sobre elementos vía paths.
L3 (XML): raw, raw-set para acceder al XML subyacente.

Las rutas (paths) son la clave para navegar documentos. Algunos ejemplos:

Path	Descripción
`/body/p[1]`	Primer párrafo del cuerpo (Word)
`/slide[1]/shape[2]`	Segunda forma de la diapositiva 1 (PowerPoint)
`/Sheet1/A1`	Celda A1 de la primera hoja (Excel)

Las unidades aceptan formatos flexibles: 2cm, 1in, 72pt. Los colores aceptan hex (FF0000), nombres (red) o RGB (rgb(255,0,0)).

4. Documentos de Word

Veamos como podemos crear un informe-resumen del repositorio pnpm, el gestor de paquetes rápido y eficiente en disco.

# Crear el documento
officecli create informe-pnpm.docx

# Título principal (negrita + tamaño grande)
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="Informe: pnpm" --prop bold=true --prop size=24pt

# Subtítulo
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="Resumen del gestor de paquetes para Node.js" \
  --prop bold=true --prop size=18pt

# Párrafo de introducción
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="pnpm es un gestor de paquetes de Node.js que destaca por su eficiencia en disco. Utiliza un sistema de almacenamiento content-addressable que permite compartir dependencias entre proyectos, ahorrando gigabytes de espacio."

# Sección: características
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="Características principales" --prop bold=true --prop size=18pt

officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="• Velocidad: hasta 2x más rápido que npm y Yarn Classic."
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="• Eficiencia: las dependencias se enlazan desde un almacén único."
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="• Monorepos: soporte nativo para proyectos multi-paquete."
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="• Seguridad: un paquete solo accede a sus dependencias declaradas."

# Tabla resumen (las celdas usan "text", no "value")
officecli add informe-pnpm.docx /body --type table \
  --prop rows=3 --prop cols=3

officecli set informe-pnpm.docx /body/tbl[1]/tr[1]/tc[1] --prop text="Gestor" --prop bold=true
officecli set informe-pnpm.docx /body/tbl[1]/tr[1]/tc[2] --prop text="Velocidad" --prop bold=true
officecli set informe-pnpm.docx /body/tbl[1]/tr[1]/tc[3] --prop text="Eficiencia" --prop bold=true

officecli set informe-pnpm.docx /body/tbl[1]/tr[2]/tc[1] --prop text="npm"
officecli set informe-pnpm.docx /body/tbl[1]/tr[2]/tc[2] --prop text="Lenta"
officecli set informe-pnpm.docx /body/tbl[1]/tr[2]/tc[3] --prop text="Baja"

officecli set informe-pnpm.docx /body/tbl[1]/tr[3]/tc[1] --prop text="pnpm"
officecli set informe-pnpm.docx /body/tbl[1]/tr[3]/tc[2] --prop text="Rápida"
officecli set informe-pnpm.docx /body/tbl[1]/tr[3]/tc[3] --prop text="Alta"

# Negrita y color en la conclusión
officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="Conclusión" --prop bold=true --prop size=18pt

officecli add informe-pnpm.docx /body --type paragraph \
  --prop text="pnpm es la opción recomendada para proyectos que buscan velocidad y ahorro de espacio."

officecli set informe-pnpm.docx /body/p[10]/r[1] --prop bold=true --prop color=1A7F37

# Guardar
officecli close informe-pnpm.docx

5. Slides de PowerPoint

Vamos a crear una presentación sobre MTMI (Manz Twitch Messaging Interface), una librería JavaScript de ManzDev para leer el chat de Twitch sin cuenta. Usaremos imágenes de fondo, fuentes concretas y elementos decorativos.

# Descargar imagen de fondo de Unsplash
mkdir -p /tmp/mtmi-assets
curl -sL "https://images.unsplash.com/photo-1550751827-4bd374c3f58b?w=1920&q=80" \
  -o /tmp/mtmi-assets/bg-tech.jpg

# Crear presentación
officecli create mtmi-deck.pptx

# --- Diapositiva 1: Portada ---
officecli add mtmi-deck.pptx / --type slide \
  --prop background="image:/tmp/mtmi-assets/bg-tech.jpg" \
  --prop transition=fade

# Overlay oscuro sobre la imagen (negro 90% opaco)
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop geometry=rect --prop x=0 --prop y=0 --prop width=33.87cm --prop height=19.05cm \
  --prop fill=000000 --prop opacity=0.9

# Barra decorativa superior (gradiente violeta)
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop geometry=rect --prop x=0 --prop y=0 --prop width=33.87cm --prop height=1.2cm \
  --prop gradient="6441FF-9B59B6" --prop opacity=0.9

# Caja semitransparente detrás del título
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop geometry=roundRect --prop x=1.5cm --prop y=5.5cm --prop width=14cm --prop height=3.5cm \
  --prop fill=000000 --prop opacity=0.05

# Título principal
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop text="MTMI" --prop font="Science Gothic" --prop size=60 --prop bold=true \
  --prop color=FFFFFF --prop shadow=000000 \
  --prop x=2cm --prop y=6cm

# Subtítulo
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop text="Manz Twitch Messaging Interface" --prop font=Jost \
  --prop size=22 --prop color=CCCCCC \
  --prop x=2cm --prop y=9cm

# Estrella decorativa
officecli add mtmi-deck.pptx '/slide[1]' --type shape \
  --prop geometry=star5 --prop x=28cm --prop y=1cm --prop width=2cm --prop height=2cm \
  --prop fill=F1C40F --prop opacity=0.7

# --- Diapositiva 2: Qué es ---
officecli add mtmi-deck.pptx / --type slide \
  --prop title="¿Qué es MTMI?" --prop background=1A1A2E \
  --prop transition=fade

# Línea decorativa bajo el título
officecli add mtmi-deck.pptx '/slide[2]' --type shape \
  --prop geometry=rect --prop x=2cm --prop y=3.6cm --prop width=6cm --prop height=0.1cm \
  --prop fill=6441FF

# Descripción
officecli add mtmi-deck.pptx '/slide[2]' --type shape \
  --prop text="Librería JavaScript para obtener información del chat de Twitch de forma sencilla, sin backend ni cuenta. Solo lectura." \
  --prop font=Jost --prop size=18 --prop color=ECF0F1 \
  --prop x=2cm --prop y=4.5cm --prop width=28cm

# Badge decorativo
officecli add mtmi-deck.pptx '/slide[2]' --type shape \
  --prop geometry=roundRect --prop x=2cm --prop y=8cm --prop width=4cm --prop height=1cm \
  --prop fill=2ECC71 --prop text="v0.0.19" --prop font=Jost \
  --prop size=14 --prop bold=true --prop color=FFFFFF

# --- Diapositiva 3: Funcionalidades ---
officecli add mtmi-deck.pptx / --type slide \
  --prop title="Funcionalidades" --prop background=0F3460 \
  --prop transition=fade

# Línea decorativa
officecli add mtmi-deck.pptx '/slide[3]' --type shape \
  --prop geometry=rect --prop x=2cm --prop y=3.6cm --prop width=6cm --prop height=0.1cm \
  --prop fill=9B59B6

# Lista de funcionalidades con bullet points
officecli add mtmi-deck.pptx '/slide[3]' --type shape \
  --prop text="💬  Mensajes y acciones del chat\n💸  Suscripciones (prime, regaladas)\n💲  Bits y cheers\n⛔  Baneos y moderación\n⚓  Raids y entradas/salidas" \
  --prop font=Jost --prop size=18 --prop color=FFFFFF \
  --prop x=2cm --prop y=4.5cm --prop width=28cm

# Cuadro decorativo lateral
officecli add mtmi-deck.pptx '/slide[3]' --type shape \
  --prop geometry=rect --prop x=31cm --prop y=4cm --prop width=0.3cm --prop height=5cm \
  --prop gradient="6441FF-9B59B6-90"

# --- Diapositiva 4: Ejemplo de código ---
officecli add mtmi-deck.pptx / --type slide \
  --prop title="Ejemplo rápido" --prop background=16213E \
  --prop transition=fade

# Línea decorativa
officecli add mtmi-deck.pptx '/slide[4]' --type shape \
  --prop geometry=rect --prop x=2cm --prop y=3.6cm --prop width=6cm --prop height=0.1cm \
  --prop fill=00FF88

# Fondo semitransparente para el código
officecli add mtmi-deck.pptx '/slide[4]' --type shape \
  --prop geometry=roundRect --prop x=2cm --prop y=4.2cm --prop width=30cm --prop height=6cm \
  --prop fill=0D1117 --prop opacity=0.85

# Bloque de código
officecli add mtmi-deck.pptx '/slide[4]' --type shape \
  --prop text='import { client } from "mtmi";\n\nclient.connect({ channels: ["manzdev"] });\n\nclient.on("message", ({ username, message }) => {\n  console.log(`${username}: ${message}`);\n});' \
  --prop font="Victor Mono" --prop size=14 --prop color=00FF88 \
  --prop x=3cm --prop y=4.8cm --prop width=28cm

# Guardar
officecli close mtmi-deck.pptx

6. Hojas de Excel

Vamos a crear una hoja de cálculo con los precios de los componentes de un PC de gama media-alta para 2026, con formato visual: cabeceras con color, bordes y negrita.

# Crear hoja de cálculo
officecli create presupuesto-pc.xlsx

# Anchuras de columna (márgenes de celda)
officecli set presupuesto-pc.xlsx /Sheet1/col[1] --prop width=22
officecli set presupuesto-pc.xlsx /Sheet1/col[2] --prop width=35
officecli set presupuesto-pc.xlsx /Sheet1/col[3] --prop width=16

# --- Cabecera (fila 1): fondo azul claro + negrita + centrado ---
officecli set presupuesto-pc.xlsx /Sheet1/A1 \
  --prop value="Componente" --prop bold=true --prop fill=D6EAF8 --prop alignment.horizontal=center
officecli set presupuesto-pc.xlsx /Sheet1/B1 \
  --prop value="Modelo" --prop bold=true --prop fill=D6EAF8 --prop alignment.horizontal=center
officecli set presupuesto-pc.xlsx /Sheet1/C1 \
  --prop value="Precio (€)" --prop bold=true --prop fill=D6EAF8 --prop alignment.horizontal=center

# --- Componentes (7) ---
officecli set presupuesto-pc.xlsx /Sheet1/A2 --prop value="Procesador"
officecli set presupuesto-pc.xlsx /Sheet1/B2 --prop value="AMD Ryzen 7 9800X3D"
officecli set presupuesto-pc.xlsx /Sheet1/C2 --prop value=499 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A3 --prop value="Placa base"
officecli set presupuesto-pc.xlsx /Sheet1/B3 --prop value="ASUS ROG Strix B850-E"
officecli set presupuesto-pc.xlsx /Sheet1/C3 --prop value=329 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A4 --prop value="RAM"
officecli set presupuesto-pc.xlsx /Sheet1/B4 --prop value="G.Skill Trident Z5 32GB DDR5"
officecli set presupuesto-pc.xlsx /Sheet1/C4 --prop value=129 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A5 --prop value="GPU"
officecli set presupuesto-pc.xlsx /Sheet1/B5 --prop value="NVIDIA RTX 5070 Ti"
officecli set presupuesto-pc.xlsx /Sheet1/C5 --prop value=849 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A6 --prop value="Almacenamiento"
officecli set presupuesto-pc.xlsx /Sheet1/B6 --prop value="Samsung 990 Pro 2TB NVMe"
officecli set presupuesto-pc.xlsx /Sheet1/C6 --prop value=179 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A7 --prop value="Fuente"
officecli set presupuesto-pc.xlsx /Sheet1/B7 --prop value="Corsair RM850x 850W 80+ Gold"
officecli set presupuesto-pc.xlsx /Sheet1/C7 --prop value=139 --prop alignment.horizontal=center

officecli set presupuesto-pc.xlsx /Sheet1/A8 --prop value="Caja"
officecli set presupuesto-pc.xlsx /Sheet1/B8 --prop value="Fractal Design North"
officecli set presupuesto-pc.xlsx /Sheet1/C8 --prop value=159 --prop alignment.horizontal=center

# --- Fila TOTAL: negrita + fondo gris claro ---
officecli set presupuesto-pc.xlsx /Sheet1/A9 \
  --prop value="TOTAL" --prop bold=true --prop fill=E8E8E8
officecli set presupuesto-pc.xlsx /Sheet1/C9 \
  --prop formula="SUM(C2:C8)" --prop bold=true --prop fill=E8E8E8 --prop alignment.horizontal=center

# --- Bordes en toda la tabla (A1:C9) ---
officecli set presupuesto-pc.xlsx /Sheet1/A1:C9 --prop border.all=thin --prop border.color=BFBFBF

# Guardar
officecli close presupuesto-pc.xlsx

7. Validar documentos

OfficeCLI permite inspeccionar documentos antes de entregarlos:

# Ver estructura del documento
officecli view informe-pnpm.docx outline
File: informe-pnpm.docx | 10 paragraphs | 1 tables | 0 images

# Ver texto plano
officecli view informe-pnpm.docx text

# Detectar problemas de formato/contenido
officecli view informe-pnpm.docx issues

# Validar contra el esquema OpenXML
officecli validate informe-pnpm.docx
Validation passed: no errors found.

# Obtener un elemento concreto en JSON
officecli get mtmi-deck.pptx '/slide[1]/shape[1]' --json

# Buscar elementos por selector
officecli query informe-pnpm.docx 'paragraph[style=Heading1]'

Usa view issues antes de entregar un documento para detectar problemas automáticos: texto que desborda, faltan alternativas de imagen, fórmulas con errores, etc.

8. Edición y plantillas

Cuando necesitas aplicar múltiples cambios de una vez, usa batch. Y si generas documentos repetitivos, merge reemplaza marcadores {{key}} con datos JSON:

# Batch: varios cambios en un solo paso
officecli batch mtmi-deck.pptx --json <<'EOF'
[{
  "command": "set",
  "path": "/slide[1]/shape[1]",
  "props": { "text": "Título actualizado" }
}, {
  "command": "set",
  "path": "/slide[2]/shape[1]",
  "props": { "text": "Contenido nuevo" }
}]
EOF

# Merge: rellenar plantilla con datos
officecli merge plantilla-factura.docx factura-001.docx \
  --data '{"cliente":"Acme","total":"$5.200","fecha":"01/09/2026"}'

También puedes hacer búsqueda y reemplazado en texto:

# Reemplazar texto en todo el documento
officecli set informe-pnpm.docx / --find "pnpm" --replace "PNPM"

# Formatear texto que coincida
officecli set informe-pnpm.docx /body/p[3] --find "eficiencia" --prop bold=true --prop color=1A7F37

9. Uso con agentes

Los ejemplos anteriores servían para entender cómo funciona officecli, pero su verdadera potencia es que un agente de IA pueda crear, leer y modificar documentos de forma automatizada. El agente ejecuta los comandos de officecli por ti: le pides un informe Word y lo genera completo, o una presentación con datos reales de una API.

Para que esto funcione, tu agente necesita saber usar officecli. Hay dos formas de integrarlo:

Skills (recomendado)

Los skills son ficheros markdown con instrucciones que le enseñan al agente a usar officecli. Al ejecutar officecli install, se detectan automáticamente los agentes instalados (Claude Code, Cursor, Copilot, etc.) y se les instala el skill. Si necesitas instalarlo manualmente:

# Install todo-en-uno (binary + skills + mcp)
officecli install
officecli install opencode
officecli install copilot

# Muestra los skills disponibles
officecli skills list

# Auto-instala el skill base de officecli en los agentes detectados
officecli skills install

# Instala el skill word en el agente opencode
officecli skills install word opencode

También puedes descargar el skill directamente y copiarlo a la carpeta de tu agente:

# Descargar el skill
curl -fsSL https://officecli.ai/SKILL.md \
  --create-dirs -o ~/.config/opencode/skills/officecli/SKILL.md

Con el skill instalado, el agente ya puede crear documentos. Sin el skill instalado, puede que el agente no conozca como funciona officecli y sea torpe al intentar crear documentos. Una vez instalados, simplemente descríbele lo que quieres: "Crea un informe Word con el resumen del proyecto X" y officecli hará el resto.

MCP (opcional)

El MCP server es una alternativa al uso directo por CLI. Expone officecli como herramientas sobre JSON-RPC, sin necesidad de acceso a terminal. Solo es interesante en estos casos:

Tu agente no tiene acceso a la terminal (algunas plataformas web o sandboxes restringidos).
Quieres exponer officecli a múltiples agentes o servicios a través de una red.

Para la mayoría de usuarios, el CLI + skill es suficiente. Si necesitas MCP:

# Muestra los MCP registrados
officecli mcp list

# Registrar MCP
officecli mcp claude
officecli mcp vscode

# Eliminar MCP
officecli mcp uninstall claude
officecli mcp uninstall vscode

Ideal para agentes

Tener un CLI para crear, modificar y gestionar documentos de Office es un recurso muy valioso, ya que puede ser utilizado por un agente para automatizar ciertas tareas de documentación o presentación:

JSON estructurado: todos los comandos soportan --json
Paths estables: cada elemento tiene una ruta navegable: /slide[1]/shape[2].
Errores descriptivos: los errores incluyen code y suggestion, por lo que es fácil autocorregir.
Sin Office: funciona en servidores, CI/CD y contenedores sin necesidad de Microsoft Office.

Para más detalles, consulta su documentación oficial y la wiki de su repositorio.