cupertino-files

Open, edit, and save Apple Pages, Numbers, and Keynote documents—anywhere
JavaScript runs. Pure TypeScript, zero runtime dependencies,
no Mac required. You work with paragraphs, cells, and slides; the bytes
take care of themselves.

Docs: https://den-frie-vilje.github.io/cupertino-files/

npm install cupertino-files

import { readFileSync, writeFileSync } from "node:fs";
import { PagesDocument, NumbersDocument } from "cupertino-files";

const doc = PagesDocument.load(new Uint8Array(readFileSync("report.pages")));
doc.replaceText("2024", "2025");
doc.appendParagraph("Conclusion", "Heading 1");
writeFileSync("report-2025.pages", doc.save());

const sheet = NumbersDocument.load(new Uint8Array(readFileSync("budget.numbers")));
const table = sheet.tables()[0]!;
table.setCell(1, 1, 143_800);
table.setFormula(1, 2, "=B2*1.25", { value: 179_750 });
writeFileSync("budget.numbers", sheet.save());

Everything you don't touch is preserved byte-for-byte
(how).
Works in Node 22 or later and modern browsers, ESM-only. Bytes in, bytes out.

The format is undocumented; this library is an ongoing
reverse-engineering of it, measured from real documents.
docs/COVERAGE.md is the always-current answer to
"does it do X?". The short version:

What you can do

Pages

• Text—find & replace, append, insert; styles and fields stay attached
• Styles—named paragraph and character styles: apply, edit, create; direct formatting too
• Layout—sections, headers & footers, page setup, margins, orientation
• Images—inline insertion, floating placement, crops, filters
• Extras—comments, footnotes, bookmarks, links, page-number and date fields, lists, table of contents

Numbers

• Cells—read and write every value type; formatting, styles, and comments survive your edits; cell comments read back with their replies
• Formulas—author them as text (=SUM(A1:A5), =Other::B2); 272 functions
• Formatting—fills, borders, alignment, wrap; number, currency, date, and duration formats; bands
• Structure—sheets and tables (add, rename, move, remove), rows and columns, merges, column widths
• More—conditional rules, cell controls, and category regrouping write too; filter sets turn on or off and switch mode, though their rules read only, as do category groups

Keynote

• Slides—add, duplicate, reorder, remove, skip; titles, bodies, presenter notes
• On a slide—a slide's content is drawables and tables, so everything under Everywhere applies: edit the text in a text box, restyle a shape, add, swap, or crop an image, copy a drawable onto another slide, edit an embedded table cell-by-cell
• Decks—slide size, auto-advance; transitions read and write; builds read, retime, and remove

Everywhere

• New documents—NumbersDocument.blank() and friends: a fresh A4 document or 16:9 deck, no template file needed
• Drawables—shapes, text boxes, and images on any page, sheet, or slide: move, resize, copy, restyle—shadows, fills, strokes, opacity
• Tables—one table model for all three apps: a table on a slide or a page reads and writes exactly like one in Numbers
• Charts—data (categories, series, values) and appearance (type, colours, gridlines, legend)
• Fidelity—byte-identical round trips; future app versions load with their new features intact
• Honesty—iWork ’09 XML and password-protected documents are detected and declined, never mis-parsed
• Audit—doc.audit() names the faults a person otherwise finds by opening the document, and save() refuses an archive missing a required field

Deeper detail, per capability and with the evidence:
the capability matrix · what each open question
waits on · the format itself.

Tools for every kind of work

• The API—typed, synchronous, documented: take the tour
• The CLI—npx -y cupertino-files dump info file.pages inspects; call runs any editing tool from the shell
• For AI agents—npx -y cupertino-files mcp: an MCP server with twenty creating, editing, and formatting tools, plus a Claude Code skill in the package
• For other implementations—a language-neutral conformance suite and format bundle, so a C++ or Rust port can check itself

More in For AI agents
and the API reference.

Development

npm install && npm test   # unit + fixture suite; never launches an app
npm run test:e2e          # macOS only: drives the real apps

Contributions are warmly welcome—CONTRIBUTING.md
shows the way, and docs/BLOCKERS.md lists questions
where a few minutes with a Mac genuinely helps. Test fixtures are real
Apple-written documents from open-source test suites and public
repositories (attribution).

Built on the shoulders of
iWorkFileFormat,
keynote-parser,
numbers-parser and
WorkKit.

Legal

An independent project, not affiliated with or endorsed by Apple Inc.
Apple, iWork, Pages, Numbers, and Keynote are trademarks of Apple Inc.,
used only to name the formats this library interoperates with. It
contains no Apple code and declines encrypted documents by design;
details in docs/LEGAL.md.

License

MIT © Ole Kristensen