Rill keeps each library on the device. The desktop app and CLI can open the same library, and cached reading works without a connection.
Choose + beside the sidebar view picker, or press A while reading. Paste a website URL or a direct RSS, Atom, or JSON Feed URL. Enter a folder name to group subscriptions. Rill fetches the feed and caches its articles.
To bring subscriptions from another reader, open Import and export through the command palette or Library actions. Import an OPML file, then refresh to fetch articles. Importing adds subscriptions without erasing the existing library.
Open Library actions, then Manage feeds, to edit a feed, change its folder, retry a failed refresh, or prepare full articles during refresh. The Feeds page identifies subscriptions with errors or no articles for more than 90 days and supports bulk selection. Unsubscribing hides feeds while preserving cached articles; adding the same URLs restores them.
The sidebar combines navigation and the article list. Use the picker below Search to choose Unread, Today, All articles, Starred, Read later, Newsletters, a folder, or a feed. Type to filter choices, press Enter to open the selected view, and Escape to dismiss the picker.
Unread shows unread posts published in the past 30 days. Older posts retain their reading state and remain available in feed views, All articles, and search. Articles opened during an Unread visit stay in the list so the next row does not move under the pointer. Leaving and returning to Unread rebuilds the view from unread articles.
History loads automatically as you approach the end of the list. Search, the view picker, and the footer stay in place while articles scroll. Library actions includes reading order, Mark view read, feed management, briefings, newsletters, and import/export. The adjacent Refresh button checks subscriptions.
Hide the sidebar to give the reader more space. The separate News stream window follows the same library and can be narrowed to a feed or folder. New articles appear when refresh completes; their arrival depends on the publisher and the refresh interval.
Opening an article uses cached full text or tries to retrieve it from the source. By default, it also marks the article read. Turn off Mark articles read when opened in General settings to change that behavior.
Pausing over a row prepares content in the background; reading also prepares the next article. Preparation alone does not mark an article read. The title and metadata appear immediately, and the body fills in without replacing prose already on screen.
Prepared articles open from local storage. If extraction or the connection fails, Rill shows cached feed content. Use Open original or O to open the source in your browser. Cached content omits remote images and embedded media.
Choose Search to open the command palette. It searches articles across the cached library, finds feeds, and runs actions such as Settings. Arrow keys select a result; Enter opens it. Escape or a click outside dismisses the palette and returns focus to the previous page. Search preserves the current article, scroll position, and unfinished form.
Drag over article text, titles, or metadata to select it, then use the platform copy shortcut. The reader toolbar's copy button copies the article URL and briefly shows a check mark.
Letter shortcuts apply in the reader, outside text fields, pickers, menus, and the command palette. In the table, Mod means Command on macOS and Ctrl on Linux.
| Action | Shortcut |
|---|---|
| Next / previous article | J / K or Down / Up |
| Toggle read, star, or read-later | M, S, Q |
| Mark the current view read | Shift M |
| Undo the last explicit reading-state change | Mod Z |
| Open original / copy article URL | O / C |
| Add a feed / refresh | A / R, or Mod N / Mod R |
| Search and commands | Mod K, Mod F, or / while reading |
| Settings | Mod , |
| Show or hide the sidebar | Mod B |
| Fullscreen | Control Command F on macOS; F11 on Linux |
| Scroll the current article or utility page | Page Up / Page Down; Home / End |
| Scroll down / up while reading | Space / Shift-Space |
| Return from a utility page to reading | Escape |
| Keyboard help | ? |
Settings contains General, Rules, Briefings, AI providers, Email, Newsletters, Sharing, Reader clients, and Activity. Save changes becomes available after an edit and shows Saved only after the preferences are stored. A failed save keeps the draft for correction. Switching sections preserves unfinished preference and rule fields.
Choose Back to reading or press Escape to return to the existing reading position. With the sidebar hidden, the back action remains beside the window controls.
A new rule defaults to "Star new articles" in the active feed or folder, or all feeds when opened from a library view. It is ready to save without entering a name or keywords. Customize rule exposes sources, actions, and optional filters for title, author, or article text, with any/all matching and exclusions.
Without filters, a rule applies to every new article in its scope. Rules run only when an article first arrives; they do not change existing articles on save or refresh. Email is never selected by default. Enabling it queues matching articles until delivery is configured.
Open Briefings to generate a local digest or use an AI provider configured in Settings. Choose a lookback of 6, 8, 12, or 24 hours. Briefings stay in the library, and email delivery is optional. Automatic generation uses the computer's time zone and requires the app or CLI daemon to be running.
Import newsletters from .eml files, or connect a dedicated IMAP folder. The receiving address belongs to your mail provider. Rotating a plus-address requires that provider's support and does not cancel subscriptions to older aliases. See Integrations for setup and data sent to each service.
The companion CLI uses the same library as the desktop. Pass --data-dir to choose another library. These examples use a separate directory and the optimized binaries from Development:
target/release/rill-cli --data-dir /tmp/rill-cli-library add https://blog.rust-lang.org/feed.xml --folder Engineering
target/release/rill-cli --data-dir /tmp/rill-cli-library refresh
target/release/rill-cli --data-dir /tmp/rill-cli-library search "Rust" --limit 10
target/release/rill-cli --data-dir /tmp/rill-cli-library infoRun rill-cli --help or rill-cli COMMAND --help for arguments. If the binaries are not on PATH, use target/release/rill-cli.
| Command | Purpose |
|---|---|
info, add, refresh, search |
Inspect the library, subscribe, fetch, and search |
import PATH, export PATH |
Import or export OPML subscriptions |
backup PATH |
Write a consistent database backup to a new file |
import-email PATH, check-mail |
Import an .eml file or poll the configured IMAP folder |
briefing --hours 8 |
Generate a local digest; add --ai to use the configured model |
settings |
Print preferences as JSON; --file PATH replaces them from a JSON file |
rules |
Print rules as JSON; --file PATH imports one JSON rule |
provider-status |
Check provider configuration without starting a session |
create-key NAME, revoke-key ID |
Create or revoke a compatibility-client key |
serve --port 8197 |
Run the loopback compatibility listener in the foreground |
daemon |
Run refresh, mailbox, scheduling, delivery, and configured listener jobs |
deliver |
Retry queued email and shares through configured providers |
demo |
Add fictional sample content to an empty library |
OPML export and backup require a destination file that does not already exist. Commands that contact external services use the configuration described in Integrations.
Rill uses the operating system's local application-data directory by default. Open Keyboard shortcuts, then Show library folder, or run rill-cli info to find it. RILL_DATA_DIR selects another default directory; an explicit --data-dir takes precedence.
library.db contains subscriptions, articles, reading state, rules, briefings, preferences, and delivery records. SQLite also uses adjacent WAL and shared-memory files while the library is open.
desktop-session.json stores the main window's reading view, selected article, loaded list, scroll positions, sidebar state, settings section, and window geometry. Reopening restores cached reading without marking an article read. An empty selection stays empty. Unsaved form edits and an open command palette do not restore.
Cached articles, search, read markers, stars, and read-later work offline. Automatic refresh uses the interval in Settings; failures keep the existing articles.
OPML contains subscriptions and folders. A database backup also includes cached content, reading state, rules, briefings, preferences, queued deliveries, and client-key hashes. It contains private reading data. The desktop session file and provider-owned credentials are separate from the database backup.
Create a backup through Import and export or rill-cli backup PATH. To restore:
- Quit Rill and stop any CLI daemon or server using the library.
- Create a new data directory and place the backup there as
library.db. - Start Rill with
--data-dirpointing to that directory. - Check the restored subscriptions, articles, and reading state before removing the original copy.
Restored preferences can resume configured jobs, including queued deliveries. Do not replace an active database or copy only library.db while its WAL database is open.