nodejs-omnifocus-bridge

nodejs-omnifocus-bridge is a read-only OmniFocus reader for Node.js and TypeScript.

It understands both OmniFocus database formats:

• the local macOS database used directly by the OmniFocus app
• the encrypted OmniFocus vault format used for synced and self-hosted setups

The package also recreates OmniFocus-style availability logic, so you can work with tasks the way OmniFocus presents them instead of just parsing raw XML.

What You Get

• a library for reading OmniFocus data into structured JavaScript objects
• a CLI for printing that data as JSON or as a terminal-friendly ASCII tree
• snapshot helpers for available, remaining, completed, dropped, or all task views

The project is intentionally read-only. It does not modify OmniFocus data.

Requirements

• Node.js 20+
• macOS for direct access to the local OmniFocus container
• encrypted vault reading also works on non-macOS systems

Install

Install the library in a project:

npm install nodejs-omnifocus-bridge

Run the CLI without a global install:

npx --package nodejs-omnifocus-bridge omnifocus-list --help

Or install the CLI globally:

npm install -g nodejs-omnifocus-bridge

CLI Quickstart

Show available tasks from the auto-detected source:

npx --package nodejs-omnifocus-bridge omnifocus-list --filter available

Read the local macOS database explicitly:

npx --package nodejs-omnifocus-bridge omnifocus-list --source local

Read an encrypted vault from disk:

OMNIFOCUS_PASSWORD="secret" npx --package nodejs-omnifocus-bridge omnifocus-list --source vault --path /path/to/OmniFocus.ofocus

Get structured JSON instead of the ASCII view:

npx --package nodejs-omnifocus-bridge omnifocus-list --json

CLI Options

• --filter <available|remaining|dropped|completed|all>
• --source <auto|local|vault>
• --path <path>
• --password <password>: supported, but avoid it because shell history and process lists can expose secrets
• --base-only
• --json
• -h, --help
• -v, --version

If a vault password is required and OMNIFOCUS_PASSWORD is not set, the CLI prompts for it in an interactive terminal.

Environment Variables

• OMNIFOCUS_PASSWORD
• OMNIFOCUS_LOCAL_PATH
• OMNIFOCUS_VAULT_PATH

Auto mode resolves sources in this order:

1. --path
2. OMNIFOCUS_LOCAL_PATH
3. OmniFocus 4 default macOS container path
4. OmniFocus 3 default macOS container path
5. OMNIFOCUS_VAULT_PATH

Library Quickstart

import {
  createSnapshot,
  readOmniFocus,
  renderTaskChart
} from "nodejs-omnifocus-bridge";

const document = await readOmniFocus({
  source: "local"
});

const snapshot = createSnapshot(document, "available");

console.log(`Available tasks: ${snapshot.filtered.tasks.length}`);
console.log(renderTaskChart(snapshot));

Examples And Reference

• Runnable examples live in examples/README.md
• Public API reference lives in docs/reference.md

Example scripts included in this repository:

• examples/available-tasks.mjs
• examples/export-json.mjs
• examples/read-vault.mjs

Public API

The root package export is intentionally focused on the main workflow:

• readOmniFocus
• resolveOmniFocusSource
• createSnapshot
• createContextTree
• createInboxTree
• createProjectTree
• renderTaskChart

Advanced APIs are still available through explicit subpath imports:

import { OmniFocusDecryptor } from "nodejs-omnifocus-bridge/crypto";
import { TaskFilterService } from "nodejs-omnifocus-bridge/filter";
import { SaxOmniFocusParser } from "nodejs-omnifocus-bridge/parser";
import { OmniFocusReader } from "nodejs-omnifocus-bridge/reader";
import { LoggerService } from "nodejs-omnifocus-bridge/utils";

Security And Privacy

• The tool reads OmniFocus data directly from your local filesystem; it does not send task data over the network.
• For encrypted vaults, prefer OMNIFOCUS_PASSWORD or the interactive password prompt over --password.
• Vaults are decrypted into a temporary directory while the command runs so the existing reader pipeline can process the files.
• The temporary directory is removed after normal execution and on common termination signals such as SIGINT and SIGTERM.
• If the process is force-killed, the operating system may leave temporary decrypted files behind in your temp directory.

macOS Permissions

If the CLI fails with EPERM or EACCES, give your terminal app:

• Full Disk Access
• Files and Folders access for the OmniFocus container path

This is especially common for:

• ~/Library/Containers/com.omnigroup.OmniFocus4/Data/Library/Application Support/OmniFocus/OmniFocus.ofocus
• ~/Library/Containers/com.omnigroup.OmniFocus3/Data/Library/Application Support/OmniFocus/OmniFocus.ofocus

After updating permissions, restart the terminal and try again.

Development

Useful local commands:

npm run check
npm run test:coverage
npm run cli:list -- --help