Getting started

A minute from clone to first journal entry.

Install

Homebrew (macOS / Linux)

brew tap avelino/outl https://github.com/avelino/outl
brew trust avelino/outl             # one-time: Homebrew 4.x requires it for third-party taps

# CLI + TUI (Linux + macOS)
brew install outl-beta              # latest beta — every push to main
# brew install outl                 # latest GA (when the first one ships)

# Desktop app (macOS only, dmg)
brew install --cask outl-desktop-beta

The desktop cask drops outl.app into /Applications. The dmg is unsigned today, so on first launch you’ll need to right-click → Open (or xattr -dr com.apple.quarantine /Applications/outl.app). CLI and desktop coexist; they share the workspace on disk through the op log.

See Homebrew tap for the channel rules, how switching between GA and beta works, and the Gatekeeper details for the desktop cask.

Desktop app on Linux

Homebrew doesn’t ship GUI casks on Linux, so the desktop app is published as direct download assets on every GitHub release. Each release carries three formats for x86_64:

# AppImage — portable, no install
curl -LO https://github.com/avelino/outl/releases/latest/download/outl-desktop-linux-x86_64.AppImage
chmod +x outl-desktop-linux-x86_64.AppImage
./outl-desktop-linux-x86_64.AppImage

Every asset ships a matching .sha256 sidecar. The CLI + TUI on Linux still install via Homebrew above.

From source

git clone https://github.com/avelino/outl.git
cd outl
cargo build --release

You need Rust 1.88+. rust-toolchain.toml pins the version, so rustup will pick it up automatically.

Drop the binary anywhere on your PATH:

cp target/release/outl ~/.local/bin/

(Or use cargo install --path crates/outl-cli if that’s your flavor.)

iOS app (TestFlight beta)

The iOS client is shipping as a public TestFlight beta:

https://testflight.apple.com/join/P2GdWAMd

Install TestFlight from the App Store, open the join link on the iPhone, accept the beta, and the outl app lands on the home screen. It writes its op log to its own iCloud Drive container (iCloud.app.outl.mobile-app). To share a workspace with the TUI, point outl --workspace at the same Documents/ directory inside the container:

outl --workspace ~/Library/Mobile\ Documents/iCloud~app~outl~mobile-app/Documents

Each device writes only to its own ops-<actor>.jsonl, so iCloud never has to merge — the CRDT does that.

Create a workspace

A workspace is just a directory. Pick a path, point outl init at it:

outl init ~/notes

You’ll get:

~/notes/
├── .outl/
│   ├── config.toml     # workspace identity + settings
│   ├── peers.toml      # P2P peers
│   └── orphans.log     # log of unmatched blocks during external edits
├── ops/                # the op log, one ops-<actor>.jsonl per device
├── pages/              # your named pages live here
├── journals/
│   └── 2026-05-25.md   # today's journal, seeded
└── templates/
    └── journal.md      # template applied to new journals

Open the TUI

outl --workspace ~/notes

It lands you on today’s journal. Press ? to see every keymap.

Or, if you cd ~/notes, just outl works — no subcommand means “open the TUI here.”

First moves

Pages you reference but haven’t created yet are real the moment you press Enter on the link — outl creates pages/<slug>.md with title:: <Name> automatically.

Try a theme

Eight built-in palettes:

outl --workspace ~/notes --theme outl
outl --workspace ~/notes --theme logseq-light
outl --workspace ~/notes --theme dracula
outl --workspace ~/notes --theme nord
outl --workspace ~/notes --theme monokai
outl --workspace ~/notes --theme solarized-dark
outl --workspace ~/notes --theme light
outl --workspace ~/notes --theme default-dark

To pin a theme for every workspace (shared between the TUI and the desktop app), edit the global config:

# ~/.config/outl/config.toml
[theme]
preset = "dracula"

[editor]
vim_mode = true
font_size = 15

The path is the same on macOS, Linux and Windows — XDG-style — so a single file holds your personal defaults across every client. The desktop app’s Settings modal writes here too; flipping the theme there updates the TUI on its next launch.

To pin a theme only for one workspace, edit its .outl/config.toml:

[theme]
preset = "monokai"

Or switch at runtime in the TUI: open the command palette with :, type theme nord, hit Enter.

Edit .md externally

Open any file in ~/notes/pages/ with VS Code, vim, Obsidian — whatever. The file is plain markdown:

title:: Avelino

- some block
- another block with [[ref]] and #tag

There are no id:: lines, no UUIDs, no HTML comments. When you save and reopen the TUI, outl matches each block back to its sidecar entry and rebuilds the op log.

Next steps

• The TUI manual — every key, every overlay, persistence rules, gotchas.
• Why outl — the pitch vs. Roam and Logseq.
• Sync, done right — what makes the algorithm interesting.