Bilig WorkPaper

https://github.com/proompteng/bilig
Admin
Formula WorkPaper runtime for Node.js services and agent tools: edit cells, recalculate, verify...
Tokens:371,874
Snippets:2,088
Trust Score:5.4
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Use @bilig/headless WorkPaper for service-side formula workflows that need explicit cell edits, recalculation, readback, and JSON persistence.
- Prefer the file-backed bilig-workpaper-mcp server when an agent needs deterministic workbook operations through MCP tools.
- Use https://bilig.proompteng.ai/mcp for stateless Streamable HTTP MCP discovery or connector smoke tests; use file-backed stdio when edits must persist to a project WorkPaper JSON file.
- Verify WorkPaper edits with read-before-write, set_cell_contents, calculated readback, and export_workpaper_document before claiming success.
- Do not use Bilig as a replacement for native Excel macros, desktop Office automation, or rich spreadsheet UI formatting.

================
CODE SNIPPETS
================
### Install and Run Quickstart Example

Source: https://github.com/proompteng/bilig/blob/main/docs/production-adoption-checklist-headless-workpaper.md

Installs the @bilig/headless package and runs a quickstart TypeScript example. Ensure the package version is pinned and verify the output signals.

```sh
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Setup and Run XLSX Recalculation Example

Source: https://github.com/proompteng/bilig/blob/main/docs/excel-file-calculation-engine-node.md

Clone the repository, navigate to the example directory, install dependencies, and run the script to execute the XLSX recalculation proof.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig/examples/xlsx-recalculation-node
npm install
npm start
```

--------------------------------

### Run End-to-End Proof with Example

Source: https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md

This snippet demonstrates how to set up and run an end-to-end proof using the maintained example from the bilig repository. It includes cloning the repository, installing dependencies, and starting the example.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
pnpm --dir examples/headless-workpaper run agent:verify
```

--------------------------------

### Install and Run Examples

Source: https://github.com/proompteng/bilig/blob/main/examples/serverless-workpaper-api/README.md

Commands to install dependencies and run various example scripts for the serverless workpaper API.

```sh
npm install
npm run test
npm run quote-approval-api
npm run next-route-handler
npm run next-server-action
npm run next-server-action-formdata
npm run next-server-action-validation
npm run framework-adapters
npm run persistence-adapters
```

--------------------------------

### Run Headless Workpaper Benchmark Example

Source: https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md

Execute these commands to install dependencies and start the headless workpaper benchmark example. This allows for evaluation of the API surface.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
```

--------------------------------

### Install and Run XLSX Recalculation Example

Source: https://github.com/proompteng/bilig/blob/main/examples/xlsx-recalculation-node/README.md

Instructions to set up and execute the XLSX recalculation example. Navigate to the example directory, install dependencies, and run the script.

```sh
cd examples/xlsx-recalculation-node
npm install
npm start
```

--------------------------------

### Setup and Run Quote Approval API with @bilig/headless

Source: https://github.com/proompteng/bilig/blob/main/docs/formula-workbooks-node-services-agent-tools.md

This snippet demonstrates the command-line steps to set up a Node.js project, install dependencies, and run a quote approval API example using @bilig/headless. It includes initializing the project, installing the library and TypeScript tools, and fetching the example script.

```sh
mkdir bilig-quote-approval
cd bilig-quote-approval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quote-approval-api.ts \
  https://raw.githubusercontent.com/proompteng/bilig/main/examples/serverless-workpaper-api/quote-approval-api.ts
npx tsx quote-approval-api.ts
```

--------------------------------

### Install and Snapshot Diff for Headless Example

Source: https://github.com/proompteng/bilig/blob/main/docs/new-contributor-guide.md

Install dependencies for the headless example and run a snapshot diff. Use this for docs-only or example-only starter issues.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run snapshot-diff
```

--------------------------------

### Setup and Run Headless Eval Example

Source: https://github.com/proompteng/bilig/blob/main/docs/why-agents-need-workbook-apis.md

Installs the @bilig/headless package and runs a TypeScript example to evaluate workbook calculations. Ensure you have Node.js and npm installed.

```sh
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo eval.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx eval.ts
```

--------------------------------

### Project Setup with npm

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Initializes a new Node.js project, configures it for ES Modules, sets a start script for TSX, and installs necessary dependencies including @bilig/headless, tsx, typescript, and @types/node.

```sh
mkdir bilig-serverless-workpaper
cd bilig-serverless-workpaper
npm init -y
npm pkg set type=module
npm pkg set scripts.start="tsx route.ts"
npm install @bilig/headless
npm install --save-dev tsx typescript @types/node
```

--------------------------------

### Install and Run Headless Workpaper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/agent-spreadsheet-tool-call-loop.md

Installs dependencies and runs the headless workpaper agent tool call loop example.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:tool-call
```

--------------------------------

### Install and run @bilig/headless quickstart

Source: https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-node-services-agents.md

Installs the @bilig/headless package and runs a quickstart script to verify its functionality. This is the shortest package sanity check for Node.js environments.

```sh
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Install Dependencies for Headless Workpaper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md

Installs dependencies for the headless workpaper example located in the `examples/headless-workpaper` directory. Use `--ignore-workspace` to skip workspace-related installations.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

--------------------------------

### Install and Run Serverless Workpaper API Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Install dependencies and run tests or specific adapter examples for the serverless workpaper API. Ensure you are in the correct directory.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
```

```sh
pnpm --dir examples/serverless-workpaper-api run test
```

```sh
pnpm --dir examples/serverless-workpaper-api run framework-adapters
```

```sh
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Install and Run Server Action FormData Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action example that handles form data for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata
```

--------------------------------

### Install and Run Serverless Workpaper API Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Installs dependencies and runs various serverless API examples for the workpaper API. Use 'quote-approval-api' for production-shaped proof.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run quote-approval-api
pnpm --dir examples/serverless-workpaper-api run next-route-handler
pnpm --dir examples/serverless-workpaper-api run next-server-action
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata
pnpm --dir examples/serverless-workpaper-api run framework-adapters
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Install and Run Next.js Route Handler Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Commands to install dependencies and run the Next.js route handler example or its focused test.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-route-handler
# or the focused example test
pnpm --dir examples/serverless-workpaper-api run test
```

--------------------------------

### Clone and Run Runnable Adapter Example

Source: https://github.com/proompteng/bilig/blob/main/docs/vercel-ai-sdk-langchain-spreadsheet-tool.md

Clone the repository, navigate to the directory, install dependencies, and run the runnable adapter example. This demonstrates dependency-free adapter functionality.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:framework-adapters
```

--------------------------------

### Install and Run Server Action Validation Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action validation example for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action-validation
```

--------------------------------

### Setup Project and Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/csv-shaped-workpaper-input-recipe.md

Initializes a new Node.js project, sets it to use ES modules, and installs the necessary Bilig Headless library along with TypeScript development tools.

```sh
mkdir bilig-csv-shaped-input
cd bilig-csv-shaped-input
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install --save-dev tsx typescript
```

--------------------------------

### Install and Run Serverless Workpaper API Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Installs dependencies and runs the Next.js server action example for the WorkPaper API.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run next-server-action
```

--------------------------------

### Setup and Run Bilig Headless Evaluation

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Installs the necessary packages and runs a TypeScript quickstart script for headless workpaper evaluation. This is useful for programmatic workbook creation and formula evaluation without a browser.

```sh
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/workpaper
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Install and Run Headless Example with npm

Source: https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md

Installs dependencies and runs the headless workpaper example when the folder is outside the monorepo using npm.

```sh
npm install
```

```sh
npm start
```

--------------------------------

### Run Persistence Roundtrip Example

Source: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md

Instructions to install dependencies and run the persistence roundtrip example from the examples directory. This verifies formula preservation and recalculation after a save/restore cycle.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run persistence
```

--------------------------------

### Clone and Install Dependencies for WorkPaper Agent

Source: https://github.com/proompteng/bilig/blob/main/docs/cloudflare-agents-workpaper-spreadsheet-tool.md

Clone the bilig repository and install necessary dependencies for the headless workpaper example. This setup is required before running the agent framework adapters.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:framework-adapters
```

--------------------------------

### Run Quote Approval API Example

Source: https://github.com/proompteng/bilig/blob/main/docs/submit-workbook-fixture.md

Installs dependencies and runs the quote approval API example for service workflows. This serves as a starting point for testing service-related fixtures.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run quote-approval-api
```

--------------------------------

### Runnable Service Storage Adapters Example

Source: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md

Instructions to install dependencies and run the persistence adapters example, which tests WorkPaper persistence with various Node.js storage solutions like Postgres, SQLite, Redis, and object storage.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Clone and Install Bilig Repository

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Steps to clone the Bilig repository and install its dependencies for the headless-workpaper example.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace

```

--------------------------------

### Run Headless WorkPaper Agent MCP Transcript Example

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md

Install dependencies and run the transcript example to test the WorkPaper agent's MCP server, including initialization, tool listing, and tool calling.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:mcp-transcript
```

--------------------------------

### Reproduce Stack Overflow Example

Source: https://github.com/proompteng/bilig/blob/main/docs/exceljs-formula-recalculation-node.md

Clone the repository, install dependencies for a specific example, and run a script to reproduce a scenario demonstrating ExcelJS formula recalculation for a Stack Overflow question.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
npm --prefix examples/recalc-bridge-workflows install
npm --prefix examples/recalc-bridge-workflows run so:exceljs-44199441
```

--------------------------------

### Run XLSX Proof Example

Source: https://github.com/proompteng/bilig/blob/main/docs/exceljs-shared-formula-recalculation-node.md

Clone the Bilig repository, navigate to the xlsx-recalculation-node example, install dependencies, and run the smoke test to verify the full recalculation loop.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig/examples/xlsx-recalculation-node
pnpm install
pnpm run smoke
```

--------------------------------

### Clone and Install Project Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/crewai-workpaper-spreadsheet-tool.md

Clone the bilig repository and install dependencies for the headless-workpaper example. This is a prerequisite for running the agent framework adapters.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

--------------------------------

### Run Framework Adapter Smoke Test

Source: https://github.com/proompteng/bilig/blob/main/docs/node-framework-workpaper-adapters.md

Clone the repository, navigate to the example directory, install dependencies, and run the framework adapters test to verify integration.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run framework-adapters
```

--------------------------------

### Clone and Run Bilig Examples

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Clone the Bilig repository and install dependencies for the serverless workpaper API example. Then, run the smoke test.

```sh
git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke
```

--------------------------------

### Run Wider Proof from Repo Checkout

Source: https://github.com/proompteng/bilig/blob/main/docs/quote-approval-workpaper-api.md

Commands to install dependencies and run tests for framework and persistence adapters from the serverless-workpaper-api example directory.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run test
pnpm --dir examples/serverless-workpaper-api run framework-adapters
pnpm --dir examples/serverless-workpaper-api run persistence-adapters
```

--------------------------------

### Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/building-a-revenue-model-with-headless-workpaper.md

Installs project dependencies for the headless-workpaper example using pnpm, ignoring workspace configurations.

```bash
pnpm --dir examples/headless-workpaper install --ignore-workspace
```

--------------------------------

### Install and Run Local Bilig App

Source: https://github.com/proompteng/bilig/blob/main/README.md

Installs project dependencies using pnpm and starts the local web application. Ensure Node.js 24+ and pnpm 10.32.1 are installed.

```bash
pnpm install
pnpm dev:web-local
```

--------------------------------

### Clone and Run Full Repo Example

Source: https://github.com/proompteng/bilig/blob/main/docs/create-bilig-workpaper.md

Clone the Bilig repository and run the serverless-workpaper-api example. This demonstrates a more comprehensive use case.

```bash
git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke
```

--------------------------------

### Setup Project Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/local-workpaper-benchmark-walkthrough.md

Clone the repository and install project dependencies using pnpm. Ensure corepack is enabled for pnpm management.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
corepack enable
pnpm install --frozen-lockfile
```

--------------------------------

### Run Bilig WorkPaper Example in Docker

Source: https://github.com/proompteng/bilig/blob/main/docs/try-bilig-headless-in-node.md

This command demonstrates how to run the Bilig WorkPaper example within a Docker container, mounting the local directory and executing the same script used in the quickstart.

```sh
docker run --rm \
  -v "$(pwd)":/eval \
  -w /eval \
  node:24-slim \
  bash -c "npm install --silent && npx tsx quickstart.ts"
```

--------------------------------

### Clone and Run Repository Example

Source: https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md

Clones the Bilig repository and runs example workflows for the WorkPaper agent, including installation, tool calls, and verification.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/workpaper-workpaper install --ignore-workspace
pnpm --dir examples/workpaper-workpaper run agent:tool-call
pnpm --dir examples/workpaper-workpaper run agent:verify
```

--------------------------------

### Install and Test Serverless Workpaper API

Source: https://github.com/proompteng/bilig/blob/main/docs/node-framework-workpaper-adapters.md

Installs dependencies and runs tests for the serverless Workpaper API example.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run test
```

--------------------------------

### Vercel Function: Installation and Execution

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Commands to install dependencies and run the Vercel Function example. This verifies the adapter's functionality.

```sh
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run vercel-function
```

--------------------------------

### Quickstart TypeScript Example for Bilig Workpaper

Source: https://github.com/proompteng/bilig/blob/main/docs/index.html

A TypeScript example demonstrating how to build, manipulate, serialize, and deserialize a Bilig WorkPaper. This snippet shows basic sheet creation, cell value reading/writing, and state persistence.

```typescript
import {
  WorkPaper,
  createWorkPaperFromDocument,
  exportWorkPaperDocument,
  parseWorkPaperDocument,
  serializeWorkPaperDocument,
} from "@bilig/workpaper";

const workbook = WorkPaper.buildFromSheets({
  Inputs: [
    ["Metric", "Value"],
    ["Customers", 20],
    ["Average revenue", 1200],
  ],
  Summary: [
    ["Metric", "Value"],
    ["Revenue", "=Inputs!B2*Inputs!B3"],
  ],
});

const inputs = workbook.getSheetId("Inputs");
const summary = workbook.getSheetId("Summary");
if (inputs === undefined || summary === undefined) {
  throw new Error("Missing sheet");
}

const before = readNumber(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }));
workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32);
const after = readNumber(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }));

const saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }));
const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved));
const restoredSummary = restored.getSheetId("Summary");
if (restoredSummary === undefined) {
  throw new Error("Missing restored Summary sheet");
}

const afterRestore = readNumber(restored.getCellValue({ sheet: restoredSummary, row: 1, col: 1 }));
console.log({ before, after, afterRestore, verified: after === afterRestore });

function readNumber(cell: unknown): number {
  if (typeof cell === "object" && cell !== null && typeof (cell as { value: unknown }).value === "number") {
    return (cell as { value: number }).value;
  }
  throw new Error(`Expected numeric cell value, got ${JSON.stringify(cell)}`);
}
```

--------------------------------

### Initialize Node.js Project and Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/node-service-workpaper-recipe.md

Sets up a new Node.js project for the workpaper service, initializes npm, configures it to use ES modules, sets a start script for `tsx`, and installs the necessary @bilig/headless library along with development dependencies for TypeScript.

```sh
mkdir bilig-workpaper-service
cd bilig-workpaper-service
npm init -y
npm pkg set type=module
npm pkg set scripts.start="tsx service.ts"
npm install @bilig/headless
npm install --save-dev tsx typescript @types/node
```

--------------------------------

### Setup and Run XLSX Recalculation Proof

Source: https://github.com/proompteng/bilig/blob/main/docs/xlsx-recalculation-proof.md

This script sets up a Node.js environment, installs dependencies, downloads the proof script, and executes it. It demonstrates the complete workflow for testing XLSX formula recalculation.

```sh
mkdir bilig-xlsx-proof
cd bilig-xlsx-proof
npm init -y >/dev/null
npm pkg set type=module
npm install @bilig/headless tsx
curl -fsSLO https://proompteng.github.io/bilig/xlsx-recalculation-proof.ts
npx tsx xlsx-recalculation-proof.ts
```

--------------------------------

### Run Range Readback Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for range readback. This demonstrates reading data within a specified range.

```sh
npm run range-readback
```

--------------------------------

### Clone and Run Headless WorkPaper Agent MCP Example

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md

Clone the repository and install dependencies to run the headless WorkPaper agent example using MCP.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:mcp-tools
```

--------------------------------

### Install and Initialize @bilig/headless in Node.js

Source: https://github.com/proompteng/bilig/blob/main/docs/javascript-spreadsheet-library-headless-node.md

Set up a new Node.js project, install the @bilig/headless package, and configure it to use ES modules.

```sh
mkdir bilig-javascript-spreadsheet-eval
cd bilig-javascript-spreadsheet-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
```

--------------------------------

### Run MCP JSON-RPC Transcript Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Starts the MCP stdio server and sends initialize, tools/list, and tools/call commands to verify workbook write/readback functionality. Requires NODE_NO_WARNINGS=1 environment variable.

```bash
NODE_NO_WARNINGS=1 npm run --silent agent:mcp-transcript
```

--------------------------------

### Short Evidence-Led Post Example

Source: https://github.com/proompteng/bilig/blob/main/docs/community-launch-pack.md

A concise post for audiences interested in Node services, coding agents, or spreadsheet automation, highlighting the @bilig/headless npm package and its quickstart process.

```text
I maintain Bilig. The public npm package is @bilig/headless.

It exists because I do not want backend jobs or coding agents clicking around a
spreadsheet UI and then treating a screenshot as proof.

The quickest way to judge the package starts from an empty directory:

1. npm install @bilig/headless
2. download the maintained eval.ts file
3. run it with tsx
4. inspect the before/after/afterRestore output

The example builds a small formula workbook, edits an input, reads the dependent
formula result, serializes WorkPaper JSON, restores it, and checks that the
restored value still matches.

Repo quickstart:
https://github.com/proompteng/bilig#try-it-in-90-seconds

This is not an Excel clone. It is for the smaller case where workbook formulas
are service logic and the code path needs readback plus persisted state.

Compatibility limits are documented:
https://github.com/proompteng/bilig/blob/main/docs/where-bilig-is-not-excel-compatible-yet.md

The benchmark claim is intentionally narrow: 99/100 comparable mean-latency
wins against HyperFormula-style workloads, structural-append-formula-rows-large
is the visible worst p95 row, and UI rendering is not part of the benchmark.

If you automate spreadsheets from Node, what would make you reject this API
quickly?
```

--------------------------------

### Run OpenAI Agents SDK WorkPaper Tool Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Execute the example for integrating OpenAI Agents SDK WorkPaper tools.

```bash
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk
```

--------------------------------

### Create and Run Bilig Workpaper Agent Starter

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Use this command to set up a new pricing agent project with a quote-approval workbook. It installs dependencies, runs the agent verification process, and builds a proof object.

```sh
npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify
```

--------------------------------

### Example Claude Desktop Interaction

Source: https://github.com/proompteng/bilig/blob/main/docs/claude-desktop-mcpb-workpaper.md

Example prompts to interact with the installed Bilig WorkPaper tools in Claude Desktop. These demonstrate listing tools, reading data, setting inputs, and reporting results.

```text
List the Bilig WorkPaper tools.
Read Summary!A1:B5, set Inputs!B3 to 0.4, read Summary!B3, and report the
recalculated value plus the persistence checks.
```

--------------------------------

### Run Invoice Totals Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for invoice totals. This is useful for calculations related to invoice data.

```sh
npm run invoice-totals
```

--------------------------------

### Run Server and Make API Calls

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Provides commands to start the server using npm and then interact with the API using curl. Demonstrates GET and POST requests to different endpoints.

```sh
npm start
```

```sh
curl -s http://localhost:8787/api/workpaper/summary
```

```sh
curl -s -X POST http://localhost:8787/api/workpaper/revenue \
  -H 'content-type: application/json' \
  -d '{"records":[{"region":"West","customers":20,"arpa":1200},{"region":"East","customers":30,"arpa":250},{"region":"Central","customers":18,"arpa":300},{"region":"North","customers":65,"arpa":180}]}'
```

```sh
curl -s http://localhost:8787/api/workpaper/summary
```

--------------------------------

### Install @bilig/headless Package

Source: https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md

Use this command to add the @bilig/headless package to your project. This is the first step to using the published package or maintained examples.

```bash
pnpm add @bilig/headless
```

--------------------------------

### Run OpenAI Agents SDK Example

Source: https://github.com/proompteng/bilig/blob/main/docs/agent-workpaper-tool-calling-recipe.md

Execute the example that demonstrates attaching WorkPaper functions as tools to an OpenAI Agent and invoking them.

```sh
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk
```

--------------------------------

### Run Budget Variance Alerts Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for budget variance alerts. This demonstrates how to identify and report budget variances.

```sh
npm run budget-variance
```

--------------------------------

### Clone and Run Bilig Repository Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Clones the Bilig repository and runs various examples from the headless-workpaper directory, demonstrating different agent interactions and functionalities.

```sh
git clone https://github.com/proompteng/bilig.git
pnpm --dir bilig/examples/headless-workpaper install --ignore-workspace
pnpm --dir bilig/examples/headless-workpaper run start
pnpm --dir bilig/examples/headless-workpaper run agent:tool-call
pnpm --dir bilig/examples/headless-workpaper run agent:openai-agents-sdk
pnpm --dir bilig/examples/headless-workpaper run agent:openai-responses
pnpm --dir bilig/examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir bilig/examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir bilig/examples/headless-workpaper run agent:framework-adapters
pnpm --dir bilig/examples/headless-workpaper run agent:verify
```

--------------------------------

### Install Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/node-service-workpaper-recipe.md

Install the `pg` driver and its TypeScript types along with the `@bilig/headless` package.

```sh
npm install pg
npm install --save-dev @types/pg
```

--------------------------------

### X / Bluesky Thread Example

Source: https://github.com/proompteng/bilig/blob/main/docs/community-launch-pack.md

A multi-part thread for X/Bluesky discussing the @bilig/headless npm package, its use cases, quickstart, benchmarks, and seeking rejection reasons from potential users.

```text
1/ I am working on @bilig/headless.

It is for the boring spreadsheet cases that end up in backend code anyway:
pricing rules, payout checks, quote calculators, import validators.

2/ The shortest eval now starts from an empty npm project:
https://github.com/proompteng/bilig#try-it-in-90-seconds

It edits an input cell, reads the recalculated value, saves WorkPaper JSON,
restores it, and checks the value again.

3/ Current benchmark artifact: 99/100 comparable mean-latency rows are faster
than the HyperFormula-style baseline.

The worst p95 row is public too: structural-append-formula-rows-large is the
visible worst p95 row, and UI rendering is not part of that benchmark.

4/ If you have shipped spreadsheet automation from Node, what would make you
reject this library in five minutes?
```

--------------------------------

### Run Agent Framework Adapters

Source: https://github.com/proompteng/bilig/blob/main/docs/crewai-workpaper-spreadsheet-tool.md

Execute the agent framework adapters for the headless-workpaper example. This command starts the CrewAI lane that exposes WorkPaper functionality.

```sh
pnpm --dir examples/headless-workpaper run agent:framework-adapters
```

--------------------------------

### Run Narrowest Check for Docs or Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/new-contributor-guide.md

Execute the command to check documentation and examples. This is the narrowest check for changes in these areas.

```bash
pnpm docs:discovery:check
```

--------------------------------

### Install and Verify @bilig/headless Package

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Use these commands to create a new project, install the @bilig/headless package, and audit its signatures and attestations. This serves as a package-integrity check.

```sh
mkdir bilig-package-trust
cd bilig-package-trust
npm init -y
npm install @bilig/headless
npm audit signatures
```

--------------------------------

### Run MCP Tools WorkPaper Server Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Execute an example of an MCP-style WorkPaper tool server using pnpm. This demonstrates how to set up and run a server that adheres to the MCP protocol.

```bash
pnpm --dir examples/headless-workpaper run agent:mcp-tools
```

--------------------------------

### Install and run the Bilig headless evaluation script

Source: https://github.com/proompteng/bilig/blob/main/docs/dev-to-workbook-apis-post.md

This command sequence installs the necessary packages and runs a TypeScript script to evaluate the Bilig headless package. It sets up a new project, installs dependencies, and downloads an evaluation script.

```sh
mkdir bilig-workpaper-eval
cd bilig-workpaper-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo eval.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx eval.ts
```

--------------------------------

### Run Persistence Round Trip Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for persistence round trip. This demonstrates saving and loading data to ensure persistence.

```sh
npm run persistence
```

--------------------------------

### Run Persistence Round Trip Example

Source: https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md

Execute this command to run the focused persistence example. It demonstrates a WorkPaper document being written to disk, restored, edited, and exported again.

```sh
npm run persistence
```

--------------------------------

### Run Fulfillment Capacity Plan Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for a fulfillment capacity plan. This is useful for planning and optimizing fulfillment operations.

```sh
npm run fulfillment-capacity
```

--------------------------------

### Install @bilig/headless Package

Source: https://github.com/proompteng/bilig/blob/main/docs/persisting-formula-backed-workpaper-documents-in-node.md

Install the necessary package for headless WorkPaper operations using pnpm.

```sh
pnpm add @bilig/headless
```

--------------------------------

### Install @bilig/xlsx-formula-recalc

Source: https://github.com/proompteng/bilig/blob/main/docs/xlsx-formula-recalculation-node.md

Install the package using npm. For a one-off CLI run, use npx.

```sh
npm install @bilig/xlsx-formula-recalc
```

```sh
npx --package @bilig/xlsx-formula-recalc xlsx-recalc --demo --json
```

--------------------------------

### Run Quote Approval Threshold Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for quote approval threshold. This demonstrates setting and managing approval limits for quotes.

```sh
npm run quote-approval
```

--------------------------------

### Install Bilig Headless Evaluation Project

Source: https://github.com/proompteng/bilig/blob/main/docs/index.html

Commands to set up a new Node.js project for headless Bilig evaluation. Ensure Node.js v22+ is installed.

```bash
mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/workpaper
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts \
  https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts
```

--------------------------------

### Local API Server and cURL Examples

Source: https://github.com/proompteng/bilig/blob/main/docs/create-bilig-workpaper.md

Start the local development server and use cURL to interact with the quote approval API. This includes testing the GET endpoint and making a POST request with sample data.

```bash
npm run dev
curl http://localhost:8788/api/quote/approval
curl -X POST http://localhost:8788/api/quote/approval \
  -H 'content-type: application/json' \
  -d '{"units":40,"listPrice":1200,"discount":0.05,"unitCost":760,"minimumMargin":0.3}'
```

--------------------------------

### Run JSON Records Input Example

Source: https://github.com/proompteng/bilig/blob/main/packages/headless/README.md

Execute the example for JSON records input. This is useful for understanding how to process data in JSON format.

```sh
npm run json-records
```

--------------------------------

### Install and Run MCP Tools from Checkout

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-spreadsheet-server-directory.md

Install dependencies and run the MCP tools agent from a local checkout of the repository. This is useful for development and testing.

```sh
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run agent:mcp-tools
```

--------------------------------

### Download Example Script

Source: https://github.com/proompteng/bilig/blob/main/docs/csv-shaped-workpaper-input-recipe.md

Downloads a maintained TypeScript example script for CSV-shaped input from the Bilig GitHub repository.

```sh
curl -fsSLo csv-input.ts \
  https://raw.githubusercontent.com/proompteng/bilig/main/examples/headless-workpaper/csv-shaped-input.ts
```

--------------------------------

### Run Headless WorkPaper Agent MCP Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Command to execute the headless WorkPaper agent example using pnpm.

```sh
pnpm --dir examples/headless-workpaper run agent:mcp-tools

```

--------------------------------

### Install Canonical MCP Server

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-spreadsheet-server-directory.md

Use this command to install and run the canonical MCP server for the Bilig WorkPaper package.

```sh
npm exec --package @bilig/workpaper@0.48.0 -- bilig-workpaper-mcp
```

--------------------------------

### Run OpenAI Responses Tool Wrapper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/agent-workpaper-tool-calling-recipe.md

Execute the example script for the OpenAI Responses API tool wrapper using pnpm.

```sh
pnpm --dir examples/headless-workpaper run agent:openai-responses
```

--------------------------------

### Install @bilig/headless and Dev Dependencies

Source: https://github.com/proompteng/bilig/blob/main/docs/unsupported-formula-troubleshooting-recipe.md

Installs the necessary @bilig/headless package and development tools like tsx and typescript for running the recipe.

```sh
mkdir bilig-unsupported-formula-eval
cd bilig-unsupported-formula-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install --save-dev tsx typescript
```

--------------------------------

### Install and List Sheets with Smithery MCP

Source: https://github.com/proompteng/bilig/blob/main/docs/llms.txt

Install a Bilig WorkPaper server using Smithery and then list available sheets. This demonstrates using Smithery for MCP server management and interaction.

```bash
npx -y smithery mcp add gkonushev/bilig-workpaper
```

```bash
npx -y smithery tool call bilig-workpaper list_sheets '{}'
```

--------------------------------

### Install Bilig WorkPaper MCP Server with Smithery

Source: https://github.com/proompteng/bilig/blob/main/docs/mcp-client-setup.md

Installs the Bilig WorkPaper MCP server using Smithery. Use this if your agent host utilizes Smithery.

```sh
npx -y smithery mcp add gkonushev/bilig-workpaper
npx -y smithery tool list bilig-workpaper
npx -y smithery tool call bilig-workpaper list_sheets '{}'
```

--------------------------------

### Clone and run Node.js workbook automation examples

Source: https://github.com/proompteng/bilig/blob/main/docs/workbook-automation-examples-node.md

Clones the repository and runs all five provided Node.js workbook automation examples using pnpm. This is for a full workflow evaluation.

```sh
git clone https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run invoice-totals
pnpm --dir examples/headless-workpaper run budget-variance
pnpm --dir examples/headless-workpaper run subscription-mrr
pnpm --dir examples/headless-workpaper run quote-approval
pnpm --dir examples/headless-workpaper run fulfillment-capacity
```

--------------------------------

### Example of File-Backed WorkPaper MCP Execution

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Illustrates a passing run of the file-backed WorkPaper MCP process. It initializes the server, lists tools, writes inputs, persists the file, reads the summary, and asserts the recalculated value.

```sh
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper pricing.workpaper.json --init-demo-workpaper --writable
```

--------------------------------

### Set up and run XLSX recalculation proof

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

This shell script sets up a directory, installs dependencies, downloads a TypeScript proof file, and executes it to demonstrate XLSX formula recalculation. It's the smallest useful check for the process.

```shell
mkdir bilig-agent-xlsx-proof
cd bilig-agent-xlsx-proof
npm init -y >/dev/null
npm pkg set type=module
npm install @bilig/headless tsx
curl -fsSLO https://proompteng.github.io/bilig/xlsx-recalculation-proof.ts
npx tsx xlsx-recalculation-proof.ts
```

--------------------------------

### WorkPaper API GET Request Example

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Example cURL command to fetch workpaper summary data from the API.

```sh
curl -s http://localhost:3000/api/workpaper/summary
```

--------------------------------

### Expected Output for Bilig Headless Quickstart

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

The expected JSON output from the Bilig Headless quickstart script. Key fields to verify are 'verified' being true and 'afterRestore' matching 'after'. The 'bytes' value may vary between package versions.

```json
{
  "before": 24000,
  "after": 38400,
  "afterRestore": 38400,
  "sheets": ["Inputs", "Summary"],
  "bytes": 999,
  "verified": true,
  "nextStep": "If this proof matches your service or agent workflow, star or bookmark Bilig: https://github.com/proompteng/bilig/stargazers"
}
```

--------------------------------

### OpenAI Agents SDK Tool Wrapper Example Output

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

This JSON output represents the expected proof from the OpenAI Agents SDK tool wrapper example. It includes the API shape, tool names used, and the write result after invoking the tools.

```json
{
  "apiShape": "OpenAI Agents SDK Agent -> tool() -> invokeFunctionTool()",
  "toolNames": ["read_workpaper_summary", "set_workpaper_input_cell"],
  "writeResult": {
    "editedCell": "Inputs!B3",
    "before": { "expectedArr": 60000, "targetGap": -34000 },
    "after": { "expectedArr": 96000, "targetGap": 5600 },
    "checks": {
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "expectedArrChanged": true
    }
  }
}
```

--------------------------------

### Run MCP Tool Server via Stdio

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Example of piping JSON-RPC requests to the MCP tool server for local stdio transport.

```sh
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize"}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | \
  npm run --silent agent:mcp-stdio

```

--------------------------------

### Recalculate Formulas in XLSX File with ExcelJS

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Integrate formula recalculation into an ExcelJS workflow. This command installs the necessary packages and runs a demo to show the recalculation process, outputting results in JSON format.

```sh
npm install exceljs @bilig/exceljs-formula-recalc
npx --package @bilig/exceljs-formula-recalc exceljs-recalc --demo --json
```

--------------------------------

### Complete Node.js WorkPaper Example

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

This comprehensive Node.js script utilizes the Bilig headless library to construct a workpaper, define its sheets and formulas, and expose utility functions for reading summary data and updating cell values. It includes helper functions for validating sheet names and cell addresses.

```typescript
import { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument, type WorkPaperCellAddress } from '@bilig/headless'

type CellInputValue = string | number | boolean | null

type SummaryReadback = {
  currentMrr: number
  nextMonthMrr: number
}

type SetInputCellArgs = {
  sheetName: string
  address: string
  value: CellInputValue
}

const workbook = WorkPaper.buildFromSheets({
  Assumptions: [
    ['Metric', 'Value'],
    ['Growth rate', 0.1],
  ],
  Revenue: [
    ['Segment', 'Customers', 'ARPA', 'MRR'],
    ['Self serve', 200, 30, '=B2*C2'],
    ['Sales', 15, 300, '=B3*C3'],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Current MRR', '=SUM(Revenue!D2:D3)'],
    ['Next month MRR', '=B2*(1+Assumptions!B2)'],
  ],
})

const summarySheet = requireSheet('Summary')
const currentMrrAddress = requireCellAddress('Summary', 'B2')
const nextMonthMrrAddress = requireCellAddress('Summary', 'B3')

const tools = {
  readSummary(range: string = 'Summary!A1:B3') {
    const parsedRange = workbook.simpleCellRangeFromString(range, summarySheet)
    if (parsedRange === undefined) {
      throw new Error(`invalid summary range: ${range}`)
    }

    return {
      range,
      values: workbook.getRangeValues(parsedRange),
      serialized: workbook.getRangeSerialized(parsedRange),
    }
  },

  setInputCell({ sheetName, address, value }: SetInputCellArgs) {
    const target = requireCellAddress(sheetName, address)
    const before = readComputedSummary()

    workbook.setCellContents(target, value)

    const after = readComputedSummary()
    const serializedWorkbook = serializeWorkbook()

    return {
      editedCell: workbook.simpleCellAddressToString(target, {
        includeSheetName: true,
      }),
      before,
      after,
      checks: {
        currentMrrChanged: before.currentMrr !== after.currentMrr,
        nextMonthMrrChanged: before.nextMonthMrr !== after.nextMonthMrr,
        serializedBytes: Buffer.byteLength(serializedWorkbook, 'utf8'),
      },
    }
  },

  serializeWorkbook,
}

console.log(tools.readSummary())
console.log(
  tools.setInputCell({
    sheetName: 'Revenue',
    address: 'B3',
    value: 25,
  }),
)

function requireSheet(sheetName: string): number {
  const sheetId = workbook.getSheetId(sheetName)
  if (sheetId === undefined) {
    throw new Error(`unknown sheet: ${sheetName}`)
  }
  return sheetId
}

function requireCellAddress(sheetName: string, a1Address: string): WorkPaperCellAddress {
  const sheetId = requireSheet(sheetName)
  const parsed = workbook.simpleCellAddressFromString(a1Address, sheetId)

  if (parsed === undefined) {
    throw new Error(`invalid cell address: ${sheetName}!${a1Address}`)
  }

  if (parsed.sheet !== sheetId) {
    throw new Error(`address ${a1Address} does not belong to ${sheetName}`)
  }

  return parsed
}

function readComputedSummary(): SummaryReadback {
  return {
    currentMrr: readNumber(currentMrrAddress, 'Current MRR'),
    nextMonthMrr: readNumber(nextMonthMrrAddress, 'Next month MRR'),
  }
}

function readNumber(address: WorkPaperCellAddress, label: string): number {
  const value = workbook.getCellValue(address) as unknown
  if (typeof value !== 'object' || value === null || !('value' in value) || typeof value.value !== 'number') {
    throw new Error(`expected ${label} to be numeric, received ${JSON.stringify(value)}`)
  }
  return Math.round(value.value * 100) / 100
}

function serializeWorkbook(): string {
  return serializeWorkPaperDocument(
    exportWorkPaperDocument(workbook, {
      includeConfig: true,
    }),
  )
}

```

--------------------------------

### Run Bilig Headless Evaluation in Docker

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Execute the Bilig Headless evaluation script within a Docker container. This method is useful for users who prefer not to alter their local Node.js version. It mounts the current directory and runs the same npm install and tsx commands.

```sh
docker run --rm \
  -v "$(pwd)":/eval \
  -w /eval \
  node:24-slim \
  bash -c "npm install --silent && npx tsx quickstart.ts"
```

--------------------------------

### WorkPaper Agent JSON Output Shape

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Example JSON output from the WorkPaper agent, detailing the API shape, package, agent name, tool names, and write result including cell edits and formula persistence checks.

```json
{
  "apiShape": "OpenAI Agents SDK Agent -> tool() -> invokeFunctionTool()",
  "package": "@openai/agents",
  "agentName": "WorkPaper verification agent",
  "toolNames": ["read_workpaper_summary", "set_workpaper_input_cell"],
  "writeResult": {
    "editedCell": "Inputs!B3",
    "before": { "expectedArr": 60000, "targetGap": -34000 },
    "after": { "expectedArr": 96000, "targetGap": 5600 },
    "checks": {
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "expectedArrChanged": true
    }
  }
}

```

--------------------------------

### Recalculate Formulas in XLSX File with Bilig

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Use this command to recalculate formulas in an existing XLSX file after changing inputs. It requires installing the xlsx-formula-recalc package and specifies input changes, output ranges, and output file names.

```sh
npm install @bilig/xlsx-formula-recalc
npx --package @bilig/xlsx-formula-recalc xlsx-recalc quote.xlsx \
  --set Inputs!B2=48 \
  --read Summary!B7 \
  --out quote.recalculated.xlsx \
  --json
```

--------------------------------

### SpreadsheetAgentTools Type Definition

Source: https://github.com/proompteng/bilig/blob/main/docs/llms-full.txt

Defines the interface for interacting with spreadsheet functionalities within an AI agent. This contract specifies methods for listing sheets, reading ranges, setting cell contents, getting cell display values, and exporting the workpaper document.

```ts
type SpreadsheetAgentTools = {
  listSheets(): Promise<string[]>
  readRange(input: { sheet: string; range: string }): Promise<unknown[][]>
  setCellContents(input: { sheet: string; cell: string; value: unknown }): Promise<{ changed: boolean }>
  getCellDisplayValue(input: { sheet: string; cell: string }): Promise<string>
  exportWorkpaperDocument(): Promise<{ json: string; bytes: number }>
}
```

--------------------------------

### Cloudflare Worker: Example cURL Commands

Source: https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md

Example cURL commands to test GET and POST endpoints of a deployed Cloudflare Worker. These demonstrate how to interact with the WorkPaper API on Cloudflare.

```sh
curl -s https://example.workers.dev/api/workpaper/summary
curl -s -X POST https://example.workers.dev/api/workpaper/revenue \
  -H 'content-type: application/json' \
  -d '{"records":[{"region":"West","customers":20,"arpa":1200},{"region":"East","customers":30,"arpa":250},{"region":"Central","customers":18,"arpa":300},{"region":"North","customers":65,"arpa":180}]}'
```

--------------------------------

### Start Local Web Development Server

Source: https://github.com/proompteng/bilig/blob/main/docs/workbook-assistant-tools-production-implementation-plan-2026-04-29.md

Initiate or reuse the local development server for the web application.

```bash
pnpm dev:web-local
```
Tokens:
Raw