---
title: "Headless Kition SDK — edit docx, xlsx, pptx, psd and more with no UI"
description: "Run Kition kits headless in Node or on a server: open, edit, check and export documents, spreadsheets, slides, PDF, PSD, SVG, DXF and more from a script. The same engines as the editors. Free, no key."
canonical: "https://developer.kition.ai/headless"
---

> Canonical HTML: [https://developer.kition.ai/headless](https://developer.kition.ai/headless)

Headless · @kition/script

# Edit pro files with no UI

The same engines as the editors, in a script or on a server: open a file, edit it through typed objects, check it, save it. Headless is free, no key.

script.ts · from docs/sdk/script.md

```
import { openHeadless } from '@kition/script/node'
import '@kition/script/kits/note'

const file = await openHeadless(
  process.env.KITION_KIT_NOTE_BINARY!,
  'Review.md',
)
const note = await file.model()
// ... edit through typed proxies, then:
await file.save()
await file.shutdown()
```

output · examples/sdk-scripts/run-headless.mjs

```
$ KITION_KITS=…/kition-kits \
  KITION_KIT_NOTE_BINARY=…/kition-note \
    node examples/sdk-scripts/run-headless.mjs
{
  "heading": "Q3 Quarterly review",
  "level": 2,
  "task": {
    "text": "Share the revenue numbers",
    "checked": true
  },
  "text": "# Team notes\n\nRevenue grew in the north.\n…- [x] Share the revenue numbers\n"
}
saved and reopened headless: {"headings":["Team notes",
  "Q3 Quarterly review"],"tasks":[{"text":
  "Share the revenue numbers","done":true}]}
```

## How it works

01

1.  Your script**openHeadless(binary, file)**
    
    From @kition/script/node. It starts kition-kits serve with the kit and hands you the document’s object model.
    
2.  The kit**kition-<kit>, with no window**
    
    Each kit has a native executable that opens, edits, renders and saves its files. It speaks the Kit Process Protocol over a private socket, with a fresh token per launch, and reaches files only through its host.
    
3.  Your files**One workspace folder**
    
    The kit writes a file only when asked to save. Or load the kit’s WebAssembly engine in Node itself, with openKitPackage.
    

## The calls that matter

02

-   [`openHeadless(binary, file, options)`](https://developer.kition.ai/docs/headless)Starts kition-kits serve with the kit’s executable and opens the file; a file that does not exist yet is created for its extension.
-   [`openKitPackage(dir)`](https://developer.kition.ai/docs/script)Loads a kit package’s WebAssembly engine in Node: open(name, bytes), create(name).
-   [`file.model({ origin })`](https://developer.kition.ai/docs/script)The document as typed objects, with the origin its changes carry.
-   [`doc.describe()`](https://developer.kition.ai/docs/script)The object model and every command the kit offers.
-   [`doc.run(async (context) => …)`](https://developer.kition.ai/docs/script)Load, edit and context.sync(): one batched change per sync; context.commands.run for commands with domain logic.
-   [`file.save() · saveAs()`](https://developer.kition.ai/docs/headless)Writes the file; nothing is written until you ask.
-   [`file.shutdown()`](https://developer.kition.ai/docs/headless)Stops the kit process.
-   [`import '@kition/script/kits/<kit>'`](https://developer.kition.ai/docs/script)Typings per published kit, generated from its schema (@kition/script/kits/note today).

## A complete example

03

One script, `quarterlyReview`, adds a review section with a task to a note, puts “Q3” before its heading and checks the task off. The SDK runs it headless on the Note kit, saves, and reads the file back in a new kit process.

kition-sdk · examples/sdk-scripts

review.mjs

```
/** Adds a review section with a task, puts "Q3 " before its heading, and checks the task off. */
export async function quarterlyReview(note) {
  return note.run(async (context) => {
    // A command with domain logic: the kit appends a section at the end of the note.
    context.commands.run('block.append', {
      markdown: '## Quarterly review\n\n- [ ] Share the revenue numbers',
    })
    const root = context.root
    root.load(['body'])
    await context.sync()
    // ... find the section, insert "Q3 " before its heading,
    // check its task off, then sync
  })
}
```

run-headless.mjs

```
import { openHeadless } from '@kition/script/node'
import { quarterlyReview } from './review.mjs'

// kition-note, reached through kition-kits serve (KITION_KITS)
const file = await openHeadless(binary, path, { stderr: 'inherit' })
let done
try {
  const note = await file.model({
    origin: { kind: 'extension', principal: 'example:quarterly-review' },
  })
  const described = await note.describe()
  assert.equal(described.capability, 'KitObjectModel 1.0')
  assert.equal(described.root, 'Note')
  assert.ok(described.commands.some((command) => command.id === 'block.append'))
  done = await quarterlyReview(note)
  assert.equal(done.heading, 'Q3 Quarterly review')
  await file.save()
} finally {
  await file.shutdown()
}

// The kit took the edits: they are in the saved file,
// which a new kit process reads.
assert.equal(readFileSync(path, 'utf8'), done.text)
const again = await openHeadless(binary, path, { stderr: 'inherit' })
```

**The same script in Node, with no executable**

The same script runs in a page, in Node, and headless. In a page it runs through `editor.document()`; here through the kit’s WebAssembly engine.

run-node.mjs · WebAssembly engine

```
import { openKitPackage } from '@kition/script/node'

const notes = await openKitPackage(join(kits, 'note-ui'))
const file = notes.create('Review.md')
const note = await file.model()
const done = await quarterlyReview(note)
const bytes = file.save()
```

## Limits and requirements

04

-   The bundle carries the executables built for its platform in `bin/<platform>/`; you can also build them from each kit’s repository (`cargo build -p kition-<kit>`). `openHeadless` also needs `kition-kits` (`KITION_KITS`, or on the `PATH`).
-   Files are confined to the workspace: nothing outside it, nothing hidden, no link out of it.
-   A kit writes a file only when asked to save, and a save commits only while the file is the version the kit read (`file_conflict` otherwise); a read-only open refuses writes.
-   Failures carry a stable reason (`KitProtocolError.reason`, the object model’s `BatchError`).

-   Headless is free, no key.
-   The same script runs in a page, in Node, and headless.

Give an agent the same kits over MCP: [Kits for agents](https://developer.kition.ai/agents).

[See the editors these engines power](https://developer.kition.ai/playground)

## Script the files your product handles

`npm i @kition/script`

[Open playground](https://developer.kition.ai/playground)
