officecli

Files (200)

• build.yml · .github/workflows/
• publish-npm.yml · .github/workflows/
• publish-pypi.yml · .github/workflows/
• publish-sdk.yml · .github/workflows/
• sdk-smoke.yml · .github/workflows/
• skill-parity.yml · .github/workflows/
• CONTRIBUTING.md
• CONTRIBUTING.zh.md
• LICENSE
• NOTICE
• README.md
• README_ja.md
• README_ko.md
• README_zh.md
• SECURITY.md
• SKILL.md
• THIRD-PARTY-NOTICES.txt
• blackhole.gif · assets/
• cat.gif · assets/
• designwhatmovesyou.gif · assets/
• efforless.gif · assets/
• first-ppt-aionui.gif · assets/
• hero-en.png · assets/
• hero-zh.png · assets/
• horizon.gif · assets/
• mars.gif · assets/
• moridian.gif · assets/
• move.gif · assets/
• ppt-process.webp · assets/
• saturn+sun.gif · assets/
• shiba.gif · assets/
• academic-paper.docx · assets/showcase/
• academic-paper.png · assets/showcase/
• annual-report.docx · assets/showcase/
• annual-report.png · assets/showcase/
• budget-tracker.png · assets/showcase/
• budget-tracker.xlsx · assets/showcase/
• employee-handbook.docx · assets/showcase/
• employee-handbook.png · assets/showcase/
• excel1.gif · assets/showcase/
• excel2.gif · assets/showcase/
• excel3.gif · assets/showcase/
• fitness-planner.xlsx · assets/showcase/
• gradebook.png · assets/showcase/
• gradebook.xlsx · assets/showcase/
• product-catalog.xlsx · assets/showcase/
• project-proposal.docx · assets/showcase/
• project-proposal.png · assets/showcase/
• restaurant-menu.docx · assets/showcase/
• sales-dashboard.png · assets/showcase/
• sales-dashboard.xlsx · assets/showcase/
• word1.gif · assets/showcase/
• word2.gif · assets/showcase/
• word3.gif · assets/showcase/
• build.sh
• officecli.entitlements · build/
• dev-install.sh
• Alien_Guide.pptx · examples/
• Cat-Secret-Life.pptx · examples/
• README.md · examples/
• …and 140 more

SKILL.md (first lines)

# officecli

AI-friendly CLI for .docx, .xlsx, .pptx. Single binary, no dependencies, no Office installation needed.

## Install

If `officecli` is not installed:

```bash
# macOS / Linux
curl -fsSL https://d.officecli.ai/install.sh | bash

# Windows (PowerShell)
irm https://d.officecli.ai/install.ps1 | iex
```

Verify with `officecli --version`. If still not found after install, open a new terminal.

---

## Strategy

**L1 (read) → L2 (DOM edit) → L3 (raw XML)**. Always prefer higher layers. Add `--json` for structured output.

**Before doc work, check Specialized Skills** (bottom of this file). Fundraising decks, academic papers, financial models, dashboards, and Morph animations need their own skill loaded first — `load_skill` once, then proceed.

---

## Help System (IMPORTANT)

**When unsure about property names, value formats, or command syntax, ALWAYS run help instead of guessing.** One help query beats guess-fail-retry loops.

`officecli help` ≡ `officecli --help`, and `officecli <cmd> --help` ≡ `officecli help <cmd>` — same content.

```bash
officecli help                                  # All commands + global options + schema entry points
officecli help docx                             # List all docx elements
officecli help docx paragraph                   # Full schema: properties, aliases, examples, readbacks
officecli help docx set paragraph               # Verb-filtered: only props usable with `set`
officecli help docx paragraph --json            # Structured schema (machine-readable)
```

Format aliases: `word`→`docx`, `excel`→`xlsx`, `ppt`/`powerpoint`→`pptx`. Verbs: `add`, `set`, `get`, `query`, `remove`. MCP exposes the same schema via the single `command` string param: `{"command":"help docx paragraph"}` (not a structured `{"format":...,"type":...}` object — the MCP tool has exactly one param, `command`, and passes it through to the CLI verbatim).

---

## Performance: Resident Mode

**Every command auto-starts a resident on first access** (60s idle timeout) — file-lock conflicts are automatically avoided. Explicit `open`/`close` is still recommended for longer sessions (12min idle):
```bash
officecli open report.docx       # explicitly keep in memory
officecli set report.docx ...    # no file I/O overhead
officecli close report.docx      # save and release
```

Opt out of auto-start: `OFFICECLI_NO_AUTO_RESIDENT=1`.

**Flush only at the non-officecli boundary.** officecli's own reads (`get`/`query`/`view`/`dump`) always see your latest edits, so you never need to save mid-workflow. Run `save` (keeps the resident) or `close` (flush + release) only **before a non-officecli program reads the file** — python-docx/openpyxl, Word, a renderer, delivery/upload. (Idle sessions auto-flush within seconds; `OFFICECLI_RESIDENT_FLUSH=each` makes every mutation flush before returning.)

---

## Quick Start

**PPT:**
```bash
officecli create slides.pptx
officecli add slides.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
officecli add slides.pptx '/slide[1]' --type shape --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm --prop font=Arial --prop size=24 --prop color=FFFFFF
```

**Word:**
```bash
officecli create report.docx
officecli add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
officecli add report.docx /body --type paragraph --prop text="Revenue increased by 25% year-over-year."
```

**Excel:**
```bash
officecli create data.xlsx
officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
officecli set data.xlsx /Sheet1/A2 --prop value="Alice"
```

---

## L1: Create, Read & Inspect

```bash
officecli create <file>               # Create blank .docx/.xlsx/.pptx (type from extension)
officecli view <file> <mode>          # outline | stats | issues | text | annotated | html
officecli get <file> <path> --depth N # Get a node and its children [--json]
officecli query <file> <selector>     # CSS-like query
officecli validate <file>             # Validate against OpenXML schema
```

### view modes

| Mode | Description | Useful flags |
|------|-------------|-------------|
| `outline` | Document structure | |
| `stats` | Statistics (pages, words, shapes) | |
| `issues` | Formatting/content/structure problems | `--type format\|content\|structure`, `--limit N` |
| `text` | Plain text extraction | `--start N --end N`, `--max-lines N` |
| `annotated` | Text with formatting annotations | |
| `html` | Static HTML snapshot — same renderer as `watch`, no server needed | `--browser`, `--page N` (docx), `--start N --end N` (pptx) |
| `screenshot` / `svg` / `pdf` / `forms` | PNG via headless browser / SVG (pptx slide) / PDF via exporter plugin / form-fields JSON via format-handler plugin | `-o`, `--screenshot-width/-height`, pptx `--grid N` |

Use `view html` for one-shot snapshots (CI artifacts, archival, diffing); use `watch` when you need live refresh or browser-side click-to-select.

### get

Any XML path via element localName. Use `--depth N` to expand children. Add `--json` for structured output. Default text output is grep-friendly: `path (type) "text" key=val key=val ...`

```bash
officecli get report.docx '/body/p[3]' --depth 2 --json
officecli get slides.pptx '/slide[1]' --depth 1          # list all shapes on slide 1
officecli get data.xlsx '/Sheet1/B2' --json
```

From shixianghua/OfficeCLI-Enhanced, Apache-2.0.