TUI Manual

The outl terminal UI is the primary way to interact with an outl workspace. It's journal-first, modal (Normal / Insert / Visual), and designed to feel familiar if you've used vim or any keyboard-driven outliner (Roam, Logseq, Obsidian).

Running

outl --workspace ~/notes          # opens the TUI on ~/notes
outl --workspace ~/notes --theme dracula
outl tui ~/notes             # explicit subcommand form
cd ~/notes && outl           # no args: opens TUI in cwd

The TUI requires a real interactive terminal. If stdout isn't a TTY (e.g. CI), it exits with a clear error instead of hanging.

Copy to clipboard

Every yank (yy / Y in Normal, y in Visual) writes clean canonical outl markdown to the OS clipboard. Two paths are tried in order:

1. arboard — direct X11 / Wayland / macOS clipboard API.
2. OSC 52 — a terminal escape sequence (\x1b]52;c;<base64>\x07) that reaches the clipboard over SSH, inside tmux, and in Chrome OS Crostini where arboard has no display server.

The status line reads yanked N block(s) → clipboard on success and yanked N block(s) (clipboard unavailable) when both paths fail.

Pasting the yanked markdown in another app reconstructs the same bullet structure. Pasting back into outl uses p (with formatting) or P (without formatting) — see Paste from clipboard below.

Paste from clipboard

p and P both read the OS clipboard via arboard (actions/paste.rs).

p — with formatting. Routes the clipboard text through outl_actions::paste_markdown when it looks like a bullet outline or spans two or more non-blank lines. Multi-line plain text is split into one block per non-blank line (blank lines are ignored). Single-line plain text falls through to a native splice at the cursor.

P — without formatting. Calls outl_actions::paste_plain directly. The raw clipboard text is inserted as a single block with no normalisation, outline parsing, or paragraph splitting. Use P when the clipboard contains identifiers with underscores, brackets, or other characters that paste_markdown would misread as markdown syntax.

Mouse capture (opt-in)

By default the TUI does not capture mouse events, preserving the terminal's native text-selection (Shift-drag to copy a URL, etc.). Set [tui] mouse_capture = true in ~/.config/outl/config.toml to enable mouse support:

The drag-copy uses the same arboard + OSC 52 dual path as the keyboard yank.

Config

The TUI reads two layers of TOML before launching:

1. Global — ~/.config/outl/config.toml (the outl-config crate; XDG-style on every OS). Same file the desktop app's Settings modal writes to, so changing your theme in the desktop reflects on the next TUI launch.

   [theme]
   preset = "dracula"
   
   [editor]
   vim_mode = true
   font_size = 15

2. Per-workspace — <workspace>/.outl/config.toml. Workspace identity ([workspace] actor_id = "...") lives here and can't move to global — it's per-device-per-workspace by design. A [theme] preset here overrides the global setting for this workspace only.

Theme precedence at startup (first hit wins): --theme CLI flag → per-workspace [theme] preset → global [theme] preset → built-in default (outl).

Modes

Normal

The default. Move between blocks, open references, run commands. No characters insert themselves — every key is a command.

Insert

Text input goes into the buffer. Esc commits (writes back to the .md), Enter commits + creates a new block.

Multi-line blocks and fenced code

A single block can hold multiple lines (Alt+Enter / Ctrl+J / Shift+Enter on kitty terminals). Used for paragraphs of prose inside one bullet and — most importantly — for fenced code blocks:

- ```lisp
  (+ 1 2)
  ```

Auto-fence: while typing inside an open code fence (the opener ``` is above the cursor but no closer has been typed yet), plain Enter is treated as a soft newline. This lets you type a fenced block naturally without remembering the soft-newline combo:

- ```lisp        ← typed `- `` ```lisp `, then Enter (+ 1 2)        ← typed body, Enter
  ```            ← typed closer, Enter
- next bullet    ← Enter here is a sibling again

The on-disk format is plain CommonMark — see docs/markdown-format.md.

Visual

A range of blocks is highlighted. j / k extends the range; the common Normal-mode keys for editing aren't available — Visual is for batch operations.

Overlays

Three modal popups can appear over the main panes. They steal the keystream while open; Esc always closes them.

Quick Switcher (Ctrl+P)

Fuzzy search across page titles, slugs, and journal dates. Today's date is always present even if the journal file doesn't exist yet.

Slash menu (/) and Command palette (:)

Two surfaces over the same command registry — pick whichever matches your muscle memory:

• / (Normal mode) opens a Notion-style filterable list. Each entry shows its name + description. Inside Insert mode, typing / triggers inline autocomplete with the same list — pick a command with Tab/Enter without leaving the buffer.
• : is the vim command line. Same registry, same args, same aliases — /q and :q are interchangeable.

Unknown commands surface in the status line as unknown command: <name>.

Workspace / navigation

Properties

Block references

Clipboard fallback: y r / /refer / /refer-embed use arboard to talk to the OS clipboard. The status line reads copied … to clipboard on success and yanked … (clipboard unavailable) on terminals / SSH sessions without a clipboard backend — the token still lives in last_yanked_ref so the in-app paste path keeps working.

Code execution

Date & time inserters

These write text at the cursor (Insert mode only). They skip the auto-commit step the other commands do, so your in-flight edit stays alive while the text lands.

/date <arg>

Garbage input (/date nope, /date +3x, invalid date) shows usage: date +Nd | -Nw | +Nm | YYYY-MM-DD on the status line.

Weekday math: date-next-<weekday> always jumps to the next occurrence of that weekday, strictly in the future. Running it on the same weekday adds 7 days, not 0 — date-next-monday on a Monday means "next Monday. ISO week year: week-num uses %G-W%V (ISO 8601), not %Y-W%V. The ISO year can differ from the calendar year on a few days around year boundaries — e.g. 2025-12-31 (Wednesday) belongs to ISO week 2026-W01, not 2025-W01.

Plugin commands

JavaScript plugins installed under <workspace>/.outl/plugins/ are loaded at startup. Each command a plugin contributes (its contributes.commands) appears in the same / slash menu, listed by its title with a plugin · <plugin-id> description so you can tell it apart from a built-in. Selecting one runs the plugin's handler; any notify message or error it produces shows as a toast. If the plugin mutates the workspace, the affected .md files are re-rendered and the current page reloads so the change is visible immediately.

Plugins are best-effort: a plugin that fails to load (bad manifest, tampered bundle, mismatched API version) is skipped with a toast, and the TUI runs normally. A workspace with no plugins behaves exactly as before.

Plugins can also register onOp hooks that fire after every workspace mutation (your edits, or ops arriving from a peer). Hooks are dispatched once per mutation; a hook that itself mutates the workspace never re-triggers itself (loop-safe).

Keybinding contribution (contributes.keybindings) and the install / permission-approval flow are not implemented yet; today the TUI surfaces plugin slash commands and runs op hooks.

Panels

┌─outl · default-dark ───────────────────────────────────────────────────┐
│ Page · Avelino                                                         │
├────────────────────────────────────────────────────────────────────────┤
│ - I am the author                                                      │
│ - some other note                                                      │
│ ───────────────────────────────────────────────────────────────────────│
│  Backlinks · 2 ref(s)                                                  │
│                                                                        │
│ 📄  Project X                                                          │
│ - led by [[Avelino]]                                                   │
│   - milestone A                                                        │
│   - milestone B                                                        │
│                                                                        │
│ 📅  2026-05-24                                                         │
│ - meeting with [[Avelino]] about Q4                                    │
├──┌NORMAL─┐ i edit  o new  K/J move …  ⇇ 2 backlinks ───────────────────┤
│  └───────┘                                                             │
└────────────────────────────────────────────────────────────────────────┘

• Outline — the current view (journal or named page). Markdown renders inline (bold/italic/code/strike); the selected/editing block is shown raw so cursor columns align with source bytes. Block references (((blk-XXXXXX))) resolve to the source block's text plus its page icon; orphaned handles render dimmed. Embeds (!((blk-XXXXXX))) — when the block contains a single embed token (whitespace OK) — render the source block and its children expanded read-only below the carrying block. Every embed row carries a ↳ prefix (root + descendants), so the expansion reads as one cohesive block. Descendants are indented by 2 * (depth + 1) spaces before their ↳ so children align under the source's text, not under the parent's ↳ . TODO/DONE checkboxes, page refs, and tags render with their normal styling inside the expansion. Recursion is capped at depth 4 to break embed cycles. The cursor-bearing block always keeps the raw ((…)) / !((…)) literal on its first row so column counting stays exact.
• Backlinks (inline) — rendered below the outline, separated by a full-width ─ rule. Every block in any other page that contains [[this]] or #this shows up with its children, grouped by source page. j/k navigation crosses the separator transparently: from the last outline block, j lands you on the first backlink; k from the first backlink walks back into the outline. Toggle the section with B. Self-references are excluded. Press i / Enter on a backlink to jump to its source page positioned on the referencing block (in-place editing lands in a follow-up).
• Status / hint — mode badge, contextual key reminder, backlink count, status messages.

Pages sidebar

Toggled by Ctrl+E (the desktop-standard "toggle sidebar" chord; \ was dropped to avoid clashing with it). Shows Today / pinned / recent pages and a mini-calendar of journals. j / k move the selection. Tab cycles the section (Today / Pinned / Recent / Calendar). Enter opens the focused page. d on a regular page arms a delete page '<title>'? y/n confirmation in the status line. y confirms, any other key cancels (and is swallowed). The g d chord (Normal mode) routes through the same confirmation flow: with the sidebar focused it deletes the highlighted row, with the outline focused it deletes the current page. Journals are refused in both paths (calendar rows are a no-op; pinned/recent journals are silently skipped). On confirm, the page root moves to NodeId::trash() via outl_actions::page::delete, the .md + .outl projections are removed, the index is rebuilt, and if the deleted page was the current view the TUI lands on today's journal. For fuzzy title jumps without the pane, Ctrl+P (quick switcher) still works with the sidebar closed.

Parser-warning banner

When you open a .md that the outl parser had to recover from (a leading # heading, a free paragraph between bullets, imported markdown that doesn't fit the dialect), the TUI shows a yellow banner above the outline:

┌─ ⚠ 3 line(s) outside outl dialect — preserved as blocks ─┐
│ line 1: # 2026-06-08 (+2 more)                           │
└──────────────────────────────────────────────────────────┘

• Every offending line is preserved as a regular block — nothing is dropped on parse, and the next save normalises the file to the dialect (- <raw>).
• The status line also carries a short ⚠ N line(s) outside outl dialect — preserved hint for terminals where the banner is not visible.
• On a clean file the banner collapses to zero height; the layout looks identical to before the feature landed.
• Source of truth: ParsedPage.warnings (outl_md::ParseWarning). Mobile + desktop render the same data via <ParseWarningsBanner> from @outl/shared, and outl doctor lists every page with active warnings.
• The behaviour is intentionally non-blocking: you can keep editing, save, navigate away. Use the warning as a hint to clean the file at your pace — outl never deletes content on your behalf.

Behavior worth knowing

• Autosave: every commit (Esc from Insert, structural ops, history navigation) writes the .md to disk and reconciles into the op log. Concurrent outl serve is safe — both routes go through outl_md::reconcile_md.
• No IDs on disk: every block has a stable ULID, but it lives in the .outl sidecar file, not in your markdown. outl serve / outl-tui rebuild that sidecar after every change.
• External edits hot-reload: when another editor writes the currently-open .md, the TUI picks it up automatically within about a second. If you're in Insert mode, it refuses to clobber your in-flight edit and writes a warning on the status line — finish typing, press Esc to commit, then Ctrl+L to reload.
• Undo bounded: 200 most recent snapshots. Older edits drop off the front. Each snapshot remembers selection + cursor so undo lands you where you were.
• Empty pages keep a bullet: deleting the last block silently re-adds an empty - so your cursor always has somewhere to go.
• Slugified filenames: [[Avelino]] lives in pages/avelino.md with title:: Avelino set automatically on first open.

Code-block execution

Fenced code blocks can be run in place. The result lands as a > **result:** subblock right below the source, and re-running updates the same subblock idempotently.

- ```lisp
  (map (lambda (x) (* x x)) (list 1 2 3 4))
  ```
  - > **result:** `(1 4 9 16)`

Built-in languages (each behind a Cargo feature, so you can strip what you don't need):

Adding another language is one file under crates/outl-exec/src/runtimes/ plus a feature flag. See docs/exec.md (forthcoming) for the contract and outl-exec/src/runtimes/lisp.rs as the canonical template.

Theming

See docs/theming.md for the palette spec, preset list, and how to set a theme via config or CLI.

What's NOT in the TUI yet

The core editor and most-used surfaces ship today. Some things are explicitly deferred:

• {{query: ...}} — inline saved queries; not yet implemented.
• Visual mode batch indent / yank / paste — only delete is wired today.
• Graph view — the desktop has it; the TUI may grow one but not a priority.
• P2P sync via iroh — works today (default transport, single-user multi-device over QUIC); the file transport (iCloud Drive) is opt-in.
• Live multi-user collaboration — multiple people editing the same workspace concurrently is still out of scope.