org-cli

---

name: org-cli version: 1.0.2 description: "Task capture, scheduling, and linked knowledge in org-mode files via the org CLI. Query, mutate, link, and search the user's org files and org-roam database." metadata: {"openclaw":{"emoji":"🦄","homepage":"https://github.com/dcprevere/org-cli","requires":{"bins":["org"],"env":["ORG_CLI_DIR","ORG_CLI_ROAM_DIR","ORG_CLI_DB","ORG_CLI_BIN","ORG_CLI_INBOX_FILE"]},"install":[{"kind":"download","label":"Download from GitHub releases: https://github.com/dcprevere/org-cli/releases"}],"scope":{"reads":["$ORG_CLI_DIR","$ORG_CLI_ROAM_DIR","$ORG_CLI_DB"],"writes":["$ORG_CLI_DIR","$ORG_CLI_ROAM_DIR","$ORG_CLI_DB"]}}}

---

org-cli

Maintain structured, linked, human-readable knowledge in org-mode files via the org CLI. Org files combine plain text with rich structure — headlines, TODO states, tags, properties, timestamps, links — and back onto a SQLite knowledge graph via org-roam.

This skill teaches the agent to manage the user's org setup on their behalf: capture tasks, schedule and close them, store knowledge in the user's roam graph, search across everything. One workspace, one store. If you also want the agent to persist *its own* memory in org, install the org-memory skill on top.

The prime directive

Everything persistent goes in org. Tasks, notes, facts, preferences, relationships, decisions — if the user says it and it has lasting value, it lives in an org file.

Never hold long-term information in chat context alone.

Never reply "got it" without a corresponding write when a write is warranted.

If a mutation fails, retry or surface the error — do not silently drop it.

Always surface the ID when you mention an item. When you create, find, reference, or list anything in org, include its short CUSTOM_ID (or UUID for roam nodes) in your reply so the user can act on it by ID. If an item has no ID (index missing — see Stable identifiers), say so and offer to backfill.

After every write, print exactly:

org-cli:  [] 

Examples:

org-cli: added TODO [k4t] ~/org/inbox.org
org-cli: added note [k4t] ~/org/inbox.org
org-cli: marked DONE [k4t] ~/org/inbox.org
org-cli: created node [3f2a-…] ~/org/roam/sarah.org

If the response JSON has no custom_id (and no id for roam nodes), print [no-id] and flag it.

No silent writes. Ever.

Shortcuts

When the user types these prefixes, act immediately.

| Action | Prefix | Target | Does | |---|---|---|---| | n note | n: | inbox | Create plain headline (no TODO, no date) | | k knowledge | k: | roam | Store/update a knowledge node | | f find | f: | all | Full-text search across headlines and roam nodes, return IDs | | t todo | t: | inbox | Create TODO, extract any date | | s schedule | s: | workspace | Reschedule matching TODO | | d done | d: | workspace | Mark matching TODO DONE |

t vs n: t creates a TODO (appears in TODO lists, can be scheduled/done). n creates a plain captured headline — a thought parked under inbox, no TODO state. Use n when the user is noting something for themselves, not committing to action. A dateless TODO is still t: with no date in the text; it just lands without SCHEDULED/DEADLINE.

Action details

In the examples below, $DIR is $ORG_CLI_DIR, $ROAM is $ORG_CLI_ROAM_DIR, and $DB is $ORG_CLI_DB.

n — create a plain note

A plain headline, no TODO keyword, no date. Does not appear in TODO lists. Use for captured thoughts, ideas, observations the user wants parked.

org add "$DIR/inbox.org" '' --db "$DB" -f json

If the user later wants to promote it to a TODO, use the ID: org todo set TODO -d "$DIR" --db "$DB".

k — knowledge in the roam graph

Store in the user's roam graph. Never create duplicates.

1. Find: org roam node find '' -d "$ROAM" --db "$DB" -f json 2. Exists → org append '' -d "$DIR" --db "$DB" -f json 3. New → org roam node create '' -d "$ROAM" --db "$DB" -f json then append.

Roam nodes live in $ROAM, never in the workspace root.

Roam nodes are identified by UUID (data.id); headlines inside them by CUSTOM_ID (data.custom_id). Surface whichever applies: Noted against Sarah [3f2a-…]: prefers morning meetings.

f — find across headlines and knowledge

Search the user's org files and roam graph, return matches with IDs. No mutation. Matches any headline — TODO, done, or plain — and any roam node.

1. org fts '' -d "$DIR" --db "$DB" -f json (full-text across titles and bodies) 2. org roam node find '' -d "$ROAM" --db "$DB" -f json 3. Merge results, group by kind, print as []