org

A CLI for querying and mutating org-mode files and managing org-roam databases, built for scripts and AI agents.

Why this exists

Grep can find text in org files but cannot understand their structure. This tool parses org-mode syntax – headlines, TODO states, priorities, tags, timestamps, property drawers, clock entries, links – and exposes that structure through a command-line interface.

The primary consumers are AI agents and automation scripts that need to query and modify an org-mode corpus without running Emacs.

Installation

Pre-built, self-contained binaries for Linux, macOS, and Windows are attached to every GitHub release. No .NET runtime required.

Linux / macOS

# Pick the asset for your platform:
#   org-linux-x64.tar.gz   org-linux-arm64.tar.gz
#   org-osx-x64.tar.gz     org-osx-arm64.tar.gz
ASSET=org-linux-x64.tar.gz
curl -L "https://github.com/dcprevere/org-cli/releases/latest/download/${ASSET}" | tar xz
install -m 755 org ~/.local/bin/org    # or: sudo mv org /usr/local/bin/
org --version

Verify checksums (optional):

curl -LO https://github.com/dcprevere/org-cli/releases/latest/download/sha256sums.txt
sha256sum -c --ignore-missing sha256sums.txt

Windows

Download org-win-x64.zip from the releases page, extract org.exe, and add its directory to PATH.

Other install methods

# Global .NET tool (requires .NET 9.0 SDK)
dotnet tool install --global OrgCli

# Build from source
git clone https://github.com/dcprevere/org-cli.git
cd org-cli
dotnet build OrgCli.slnx

Quick start

# What do I need to do today? (TODOs due today + overdue)
org today -d ~/org

# View today's full agenda (all scheduled + deadlines)
org agenda today -d ~/org

# List all headlines, filter by TODO state and tag
org headlines --todo TODO --tag work -d ~/org

# Set a headline to DONE (by short ID -- no file needed)
org todo k4t DONE

# Add a new headline (auto-assigns a short CUSTOM_ID)
org add tasks.org "New task" --todo TODO --tag project --scheduled 2026-03-01

# Assign short IDs to all existing headlines
org custom-id assign -d ~/org

# View all TODOs with filters
org todos --state TODO -d ~/org
org todos --state TODO --unscheduled -d ~/org
org todos --state TODO --overdue -d ~/org
org todos --search "meeting" --due-before 2026-03-01 -d ~/org

# Change a TODO state
org todo k4t DONE
org todo tasks.org "Pay rent" DONE

# Search across files
org search "meeting.*notes" -d ~/org

# JSON output for scripting
org today -d ~/org -f json

# Sync and query an org-roam database
org roam sync -d ~/org
org roam node list -d ~/org

What it does

Org file operations

• Headlines – list, filter by TODO state / tag / level / property, with tag and property inheritance. Each headline shows its short CUSTOM_ID for easy reference.
• Mutations – set TODO state, priority, tags, properties, SCHEDULED, DEADLINE; respects repeaters, per-keyword logging, LOGBOOK drawers. Commands accept a bare CUSTOM_ID instead of <file> <identifier> when an index exists.
• Clock – clock in/out, clock reports with per-headline and grand totals
• Refile – move subtrees within or across files, with level adjustment
• Archive – move subtrees to .org_archive with metadata stamps
• Search – regex search with context (containing headline, file, line number)
• Links – resolve id:, file:, fuzzy, and abbreviated links across the document set
• Export – convert via pandoc to any supported format
• Batch mode – execute multiple mutations atomically from JSON on stdin

Todos

View and filter all TODO headlines across your org files.

• org todos – list all headlines with a TODO state
• --state TODO / --state DONE – filter by state
• --scheduled / --unscheduled – filter by presence of SCHEDULED date
• --overdue – items where SCHEDULED date is before today
• --due-before <date> / --due-after <date> – date range filtering
• --priority A – filter by priority
• --tag work – filter by tag
• --file "personal" – filter by filename substring
• --search "meeting" – case-insensitive title search
• --sort scheduled|deadline|priority|title|file – sort output (default: scheduled)
• --reverse – reverse sort order
• All filters are combinable

Agenda

Queries org files directly (no database needed).

• org today – all non-done TODOs due today or overdue, split into sections
• Today/week views with overdue detection
• TODO list with state and tag filtering
• Timed items (SCHEDULED: <2026-03-01 Mon 14:00>) sort before untimed
• Timestamp range support (<start>--<end>)
• All list output uses aligned columns (like docker ps)

Org-roam

Manages an org-roam v2 SQLite database, compatible with Emacs org-roam (schema version 20).

• Sync files to database (incremental or forced)
• Node CRUD (file-level and headline-level nodes)
• Backlinks, tags, aliases, refs
• Link management

Index and CUSTOM_ID

org index builds a SQLite headline index for fast full-text search and CUSTOM_ID resolution.

• org add auto-assigns a short base36 CUSTOM_ID (e.g. k4t) to new headlines when an index exists
• org custom-id assign backfills CUSTOM_IDs on all existing headlines that lack one
• With CUSTOM_IDs, most commands accept a bare ID instead of <file> <identifier>: org todo k4t DONE
• org fts provides FTS5 full-text search over indexed headlines

For AI agents

• org schema outputs a machine-readable JSON description of all commands and their arguments
• org batch accepts a JSON command array on stdin for atomic multi-step operations
• -f json on all commands for structured output with {"ok":true,"data":...} envelopes
• --dry-run previews mutations without writing
• org completions bash|zsh|fish for shell integration

See docs/agents.org for a guide to building a knowledge base with an AI agent.

OpenClaw integration

This repo ships two OpenClaw plugins that put org in front of an AI agent:

• org-cli – task capture, scheduling, and a knowledge graph for your org files. The day-to-day agent-as-secretary case.
• org-memory – extends org-cli so the agent also keeps its own memory (daily notes, learned facts, a linked knowledge graph) in a separate org workspace. Install on top of org-cli if you want that layer.

# Manage your own org files
openclaw skill install org-cli

# Optional: also let the agent persist its own memory in org
openclaw skill install org-memory

Once installed you talk to the agent naturally and it drives org for you:

• t: submit taxes in 3 weeks – agent creates a scheduled TODO in your inbox
• n: think about hanging pictures up – plain captured headline, no TODO state
• k: Sarah prefers morning meetings – agent stores a fact in your roam graph against Sarah
• d: groceries – agent resolves the headline by short CUSTOM_ID and marks it DONE
• s: taxes to next Friday – agent reschedules
• f: sacra – agent searches across your headlines and roam nodes
• "What's due today?" – agent runs org today

With org-memory loaded you additionally get @a-prefixed shortcuts (@at:, @an:, @ak:, @ad:, @as:, @af:) that target the agent’s own workspace.

The plugins are what make org today, short CUSTOM_IDs, and org batch actually useful day-to-day – agenda queries, graph links, and file-less mutations are the things flat-text agent memory cannot do.

See integrations/openclaw/README.md for an overview, or each plugin’s README for install and env var details.

Configuration

Configuration is resolved in order (later overrides earlier):

1. Built-in defaults
2. XDG config file ($XDG_CONFIG_HOME/org-cli/config.json)
3. Environment variables (ORG_CLI_LOG_DONE, ORG_CLI_DEADLINE_WARNING_DAYS, etc.)
4. CLI flags (--config, --log-done, --deadline-warning-days)
5. Per-file in-buffer settings (#+TODO:, #+STARTUP:, #+PRIORITIES:)

See docs/usage.org for the complete configuration reference.

Project structure

src/OrgCli.Org/    Parser library. Types, parsers, writer, mutations, agenda, config, batch mode.
src/OrgCli.Index/  Headline index. SQLite FTS5, CUSTOM_ID generation and resolution.
src/OrgCli.Roam/   Roam DB layer. Database, sync, node operations.
src/OrgCli/        CLI entry point.
tests/OrgCli.Tests/

Building and testing

dotnet build OrgCli.slnx
dotnet test OrgCli.slnx

Non-goals

• Interactive or TUI features. This is a tool for scripts, not humans at a terminal.
• Tables, spreadsheets, babel/code block evaluation.
• Capture templates. Appending to a file is trivial; no tool needed.
• File watching. Sync is explicit.

License

MIT