lilmd - Markdown as a Database for Agents
lilmd is a CLI for working with large MD files designed for agents.
Wait, but why? Agent knowledge, docs, memory keeps growing. lilmd allows you to dump it all in one file and effeciently read/write/navigate its contents.
Features:
- fast navigation, complex read selectors, link extraction
- complex section selectors
- designed to save as much context as possible
- can write, append, remove entire sections
- can run in Node/Bun
- optimized for speed
- can be used by humans and agents
- uses Bun as tooling: to test, control deps etc.
Install
# global install > npm i -g lilmd # or run without installing > npx lilmd file.md > bunx lilmd file.md
Help
# start here! # both commands print short documentation for the agent > lilmd > lilmd --help
Overview & table of contents
First, the agent gets file overview and table of contents.
# renders toc + stats; line ranges are inclusive, 1-indexed # --depth=N to limit nesting, --flat for a flat list > lilmd file.md file.md L1-450 12 headings # lilmd L1-450 ## Getting Started L5-80 ### Installation L31-80 ## Community L301-450
Reading sections
> lilmd read file.md "# lilmd" > lilmd file.md "# lilmd" # alias! # prints the contents of the lilmd section # descendant selector (any depth under the parent) > lilmd file.md "Getting Started > Installation" # direct child only > lilmd file.md "Getting Started >> Installation" # level filter (H2 only) > lilmd file.md "##Installation" # exact match (default is fuzzy, case-insensitive) > lilmd file.md "=Installation" # regex > lilmd file.md "/install(ation)?/" # by default no more than 25 matches are printed; if more, lilmd prints a hint # about --max-results=N # --max-lines=N truncates long bodies (shows "… N more lines") # --body-only skips subsections, --no-body prints headings only
For humans only
# --pretty renders the section body as syntax-highlighted terminal markdown # (for humans; piped output stays plain unless FORCE_COLOR is set) > lilmd file.md --pretty "Installation" # nicely formatted markdown
Searching & extracting
> lilmd ls file.md "Getting Started" # direct children of a section > lilmd grep file.md "pattern" # regex search, grouped by section > lilmd links file.md ["selector"] # extract links with section path > lilmd code file.md "Install" [--lang=ts] # extract code blocks
Writing
lilmd treats sections as addressable records: you can replace, append,
insert, move, or rename them without rewriting the whole file. Every write
supports --dry-run, which prints a unified diff instead of touching disk —
perfect for agent-authored edits that a human (or another agent) reviews
before applying.
> lilmd set file.md "Install" < body.md # replace section body > lilmd append file.md "Install" < body.md > lilmd insert file.md --after "Install" < new.md > lilmd rm file.md "Old" > lilmd mv file.md "From" "To" # re-parent, fixes heading levels > lilmd rename file.md "Old" "New" > lilmd promote|demote file.md "Section" # shift heading level ±1
Output
# human-readable by default; --json for machine output # use - as filename to read from stdin > cat big.md | lilmd - "Install"