Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

First launch

The first launch opens a short setup: a welcome, Connect your blyg (or Skip, just try it with sample data), AI (off until you switch a provider on; installed claude / codex CLIs are detected), and Buttons or keyboard? (show-buttons). esc skips it at any step.

Then comes an optional interactive tour of the real window: each step highlights a part of it and waits for you to press the key (⌘N, ⌘T, ⌘⏎, ⌘3, ⌘G, ⌘Y, ⌘R, ⌘J, ⌘K, ⇧⌘C, ⇧⌘P…). It covers writing, reading, lineage, the notes drawer, the browser pane, and extensions: the bundled markdown-notes, reading-time and inspect run on sample notes during the tour, even if yours are off. The tour runs on sample data, so your own blyg isn’t touched, nothing it does changes your config file, and your posts come back when it ends. Replay it from Help › Burrow Tutorial or Settings (⌘,) › Help, or set tutorial-on-launch = true to see it every time.

After an update, the first launch opens the tour on a What’s new card: ⏎ starts at the steps that teach the new things (each says NEW IN its version), Take the whole tour starts at the beginning, and esc skips it. If your read marks stop syncing between Macs after an update, see the FAQ.

Coming from another feed reader? Blyg › Import Subscriptions from OPML… brings its feeds along (see the FAQ).

Connecting your blyg

Burrow works with any blyg running blygger-studio 0.47 or later, stock and unmodified: no server patches. On an older blyg everything syncs except posts with labelled links, which wait until the blyg is updated, and Burrow tells you so (see Server requirements). No blyg yet? Try the app on the sample data.

The Connect step asks for your blyg’s address (such as https://blyg.example.com, including any path it lives under) and how to sign in:

  • Sign in with browser (the default, studio 0.28 or later): your browser opens your studio’s sign-in and asks you to allow Burrow. Burrow keeps the grant in your Keychain and renews it in the background; after 30 days, or if you revoke it in the studio (More › Client access), it asks you to sign in again.
  • API token: make one in your studio under More › Client access (REST API, with every permission; allow reading:state, on studio 0.39+, so read marks sync) and paste it. It lasts 30 days.
  • Studio password, as a fallback.

It checks them with the server before saving anything, and says plainly what’s wrong:

  • the address can’t be reached;
  • the password or the token is wrong, or the token lacks a permission (it names which);
  • there’s no studio sign-in at that address;
  • the server is older than blygger-studio 0.9.

The sign-in, token or password then goes in your Keychain and the address into the config file as blyg-url, and the app loads your posts. If the blyg runs a studio older than 0.47, Burrow says “Your blyg needs updating” as it connects (and when it starts), keeps a notice in the status bar with an Update your blyg link, and holds back only posts with labelled links until it’s updated. Burrow › Disconnect… forgets both, and can also delete the local copy.

If your blyg later refuses Burrow’s sign-in (a token expired or was revoked, or the server changed), Burrow stops syncing instead of retrying, keeps every change waiting on your Mac, and opens the sign-in sheet to say why. Signing in again sends what waited.

The window

There’s one window. At the top is the omnibar: type to filter your posts, ↑/↓ to preview each one, ⏎ to open it, and ⏎ with no match to start a new draft with what you typed. ⌘N opens an empty editor for a new post (a scratch note until you make it a draft). esc goes back to the omnibar. The status bar at the bottom shows the post’s kind (◦ fragment or ≡ thread, click to switch), the character count, the sync state (synced, saved on this Mac, syncing…, offline · N changes waiting) and the version (draft, public v3, public v3 · unpublished edits).

A quiet toolbar in the title bar has New, Make draft, Publish, the three views (Write, Preview, Full editor), Versions, Generate, Delete or Withdraw, and Quick capture. Every tooltip shows the shortcut, so the buttons teach the keys, and a greyed-out button says why (“Too long for a fragment. ⌘T makes it a thread”). Narrow windows get icons only. show-buttons = false (or Settings, ⌘,) gives the keyboard-only window.

⌘R switches to reading, and ⌘R again comes back to your posts. Every shortcut is listed in Keyboard shortcuts.

Settings

Settings (⌘,) covers the common options: the writing and interface fonts and size, theme, layout, the quick-capture hotkey, buttons, AI accounts, and the tutorial (Help). Everything is also in the plain-text config file, which Settings writes back to without touching your comments.

Burrow comes with a Tufte-style light and dark look that follows macOS (see Themes), and switchable writing and interface fonts: Literata, Inter, Source Serif 4, iA Writer Quattro and ET Book are bundled, and system fonts such as New York, Charter, SF Pro and Menlo work too (blygger +list-fonts lists them). ⌘+ and ⌘− change the text size.

Offline, and conflicts

Nothing waits on the network. Every keystroke is saved on your Mac first; edits sync shortly after you stop typing, and queue up while you’re offline. The status bar shows how many changes are waiting.

When the server changed under you (say, you edited the same post in the web studio), a side-by-side sheet shows On this Mac and On the server: press 1 to keep yours, 2 to take the server’s, or 3 to keep both.