outl

Local-first outliner. Markdown is the source of truth. Sync that doesn't corrupt your tree when two devices edit offline.

Inspired by Roam Research and Logseq. Tree CRDT sync (Kleppmann et al. 2022), per-device append-only op log, IDs in a sidecar so the .md you see is the .md you wrote.

• Why outl? → outl.app/docs/why-outl.html
• Sync, done right: → outl.app/docs/sync.html
• CRDT walkthrough: → outl.app/docs/crdt.html

Install

# macOS / Linux via Homebrew (beta channel — every push to main)
brew tap outlmd/outl https://github.com/outlmd/outl
brew trust outlmd/outl # one-time, third-party tap
brew install outl-beta # TUI/CLI/MCP
brew install --cask outl-desktop-beta # GUI

iOS beta on TestFlight: join here. Point the TUI at the same iCloud Drive container (<container>/Documents/) and both clients share a workspace.

Android: a signed arm64 APK (outl-android-arm64.apk) rides every release. Sideload-only for now — not on Play, and each release is signed with a fresh key, so a new build means uninstalling the old one first (#171).

• From source / channels: → getting started, homebrew

Quick start

outl init ~/notes              # scaffold a workspace
outl --workspace ~/notes       # opens the TUI on today's journal

Press ? for keymap, : for the command palette, Ctrl+P to fuzzy-jump.

• Tutorial (15 min)
• TUI manual
• CLI reference
• Markdown dialect
• Shortcuts

Coming from Logseq or Roam?

outl import logseq ~/path/to/logseq-graph ~/notes
outl import roam ~/Downloads/backup.json ~/notes

The importers (Roam, Logseq, Obsidian — or auto to detect) resolve ((uid)) block refs and {{embed}}s into real outl block references, keep folded state, and translate each dialect. Everything touched is counted in the import report — run with --dry-run first to measure fidelity against your backup. Anything unresolvable stays as ((unresolved:UID)) for manual triage.

Contributing

• Developer setup
• Contributing guide
• Architecture
• Roadmap — where the project is going

Background reading

The engineering decisions behind outl on avelino.run:

• File sync isn't trivial — why concurrent file moves are a distributed-systems problem that Dropbox and Google Drive still get wrong.
• From paper to outliner — the gap between "the CRDT converges" and "the app ships": projections, content-addressable reconciliation, surviving iCloud's lazy materialisation.

License

MIT.