Folo User Guide

Folo — "Follow everything in one place" — is an open-source, AI-native information reader. It pulls articles, social posts, pictures, videos, audio, and notifications from across the web into a single, noise-free timeline. You subscribe to feeds and curated lists, read distraction-free, and let built-in AI translate and summarize as you go. Folo runs in your browser, as a desktop app (Windows, macOS, Linux), on mobile (iOS, Android), and from your terminal via the official CLI.

This guide is for people who use Folo. It covers installing the app, signing in, subscribing to and organizing content, reading with AI assistance, automating with actions and integrations, and driving Folo from the command line. Architecture, deployment, and internals live in the companion Admin Guide.

Note

Folo is under active development. Features described here are derived directly from the application source code at the documented commit. The hosted product may add or refine features after that point.

1. Choose Your Version

Folo ships as several clients that all sign in to the same account and sync the same subscriptions. Pick the one that fits how you read.

Tip

The desktop app is the most capable client and the recommended home base. The web app is the fastest way to try Folo with zero setup. The CLI complements either — it shares the desktop's sign-in automatically.

All clients are free and open source under the AGPL-3.0 license.

2. Quick Start

The fastest path from zero to reading:

1. Open Folo. Go to app.folo.is in any browser, or install the desktop/mobile app (see Installation).
2. Create an account or sign in. Use Google, GitHub, or Apple, or register with an email and password. See Accounts & Sign-In.
3. Add your first feed. Click Add (or +), paste a website or RSS URL, and subscribe. Folo auto-discovers the feed for most sites.
4. Read. Your subscriptions appear in the left column; new entries flow into the center timeline. Click an entry to read it.
5. Try the AI. Open any article and use Summary for a one-paragraph TL;DR or Translation to read it in your language.

Left column            Center timeline           Reading pane
─────────────          ───────────────           ────────────
View tabs              Entry list                Article content
  All                    • Headline 1              Title
  Articles               • Headline 2              Author · date
  Social Media           • Headline 3              Body (clean reader view)
  Pictures               ...                       AI: Summary / Translate
  Videos
  Audios
  Notifications
Subscriptions
  ▸ Category
    · Feed A
    · Feed B

Tip

Press Cmd/Ctrl + K anywhere in the desktop/web app to open the command palette and jump to any action without hunting through menus.

3. Installation

Folo is distributed through official app stores, direct downloads, and community package managers. Choose your platform below.

Web

No installation required. Open app.folo.is and sign in. The web app is a Progressive Web App (PWA), so you can also "Install" it from your browser's address bar for an app-like window.

macOS

• Mac App Store — search for Folo - Follow Everything, or open the listing.

• Direct download — grab the .dmg from the GitHub Releases page.

• Homebrew (community-maintained):

  brew install --cask folo
  

Windows

• Microsoft Store — open the listing.
• Direct download — grab the installer from GitHub Releases.
• Scoop (community-maintained manifest folo).

Linux

• Direct download — grab the AppImage from GitHub Releases.
• Arch Linux — install folo-appimage from the AUR (community-maintained).
• Nix — install the follow package from nixpkgs (community-maintained).

iOS

Install Folo - Follow Everything from the App Store.

Android

• Google Play — open the listing.
• Direct APK — download from GitHub Releases.

Note

The desktop and mobile apps update automatically. Folo for Windows is code-signed via SignPath Foundation; macOS/iOS builds are notarized through the Apple Developer Program; and every released file carries a GitHub artifact attestation you can verify for provenance.

Installing the CLI

The Folo CLI is a separate npm package (folocli) that exposes the folo command. You do not need to clone the repository to use it.

# Run without installing
npx folocli@latest --help

# Or install globally
npm install -g folocli

Usage: folo [options] [command]

Folo CLI client for structured automation

The CLI requires Node.js 18 or newer. See The Folo CLI for the full command reference.

4. Accounts & Sign-In

A Folo account syncs your subscriptions, read state, collections, and settings across every client. Authentication is handled by Folo's account service (api.folo.is).

Sign-in methods

Two-factor authentication (2FA)

Folo supports time-based one-time-password (TOTP) two-factor authentication. When 2FA is enabled on your account, after entering your password you'll be prompted for the 6-digit code from your authenticator app. On the desktop app you can choose Trust this device to skip the prompt on future sign-ins from the same machine.

Tip

Desktop login troubleshooting. If OAuth sign-in doesn't complete in the desktop app, sign in at app.folo.is in your browser, copy the __Secure-better-auth.session_token cookie value, and paste it into the desktop app's manual token field. This is a known fallback used by the development team.

Membership roles

Folo accounts carry a role that governs limits such as feed and RSSHub subscription counts:

Your current role and remaining quota are visible in Settings → Account and via the CLI folo whoami command.

5. Core Concepts

A few ideas explain almost everything in Folo. Learn these once and the rest of the app is intuitive.

Feed : A single source you subscribe to — an RSS/Atom feed, a website Folo auto-discovers a feed for, an RSSHub route, or a social/media source.

Subscription : Your relationship to a feed: which view it belongs to, its category, a custom title, and whether it's private. Unsubscribing removes the feed from your timeline.

List : A curated bundle of feeds that someone (possibly you) publishes. Subscribing to a list follows all of its feeds at once. Some lists are free; some charge a fee.

View : A content lens. Folo separates content by type so a wall of tweets never drowns your long-reads. Folo's views are:

Timeline : The center stream of entries for the currently selected view, feed, list, or category.

Entry : A single item in a feed — an article, post, image, video, or audio episode.

Collection (star) : Entries you save for later. Collected entries are searchable and synced across devices.

Category : A user-defined folder that groups subscriptions within a view (e.g. "Tech", "News").

6. Subscribing & Discovering Content

Add a feed by URL

1. Click Add / + in the subscription column.
2. Paste a URL — a website homepage, an article page, or a direct RSS/Atom feed URL. Folo attempts feed auto-discovery from the page's HTML.
3. Choose the view (Articles, Social Media, etc.) and optionally a category and custom title.
4. Mark it private if you don't want it shown on your public profile.
5. Subscribe.

Discover sources

Folo's Discover screen helps you find sources without knowing a feed URL:

• Search — search feeds and lists by keyword.
• RSSHub — browse and subscribe to thousands of RSSHub routes that turn sites without native feeds (social networks, forums, shopping, anime, finance, and more) into subscribable feeds. Routes are organized into categories such as social-media, new-media, traditional-media, bbs, blog, programming, design, live, multimedia, picture, anime, shopping, game, reading, journal, and finance.
• Trending — see what other Folo users are subscribing to, filterable by time range (1 day, 3 days, 7 days, 30 days) and language.

Tip

Subscribing to lists is the fastest way to bootstrap a topic. A single well-curated list can add dozens of high-quality feeds to a view in one click.

Import existing subscriptions (OPML)

Moving from another reader? Import your OPML file from Settings → Subscriptions → Import, or use the CLI:

folo opml import --items "https://example.com/feed.xml,https://blog.dev/rss"

You can also export your current subscriptions as OPML at any time for backup or migration (see The Folo CLI).

Note

Some accounts have an OPML import size limit. If a large import is truncated, import in smaller batches.

The Inbox

Folo can give you a personal inbox email address. Forward newsletters (or have services email you) at that address and they appear as entries in Folo — handy for email-only newsletters.

7. Reading

Views and layouts

Switch views using the tabs at the top of the subscription column. Each view uses a layout suited to its content: Articles use a list, Social Media uses a wide single column, and Pictures and Videos use a grid. Select All to merge every subscription into one stream.

Within a view you can drill down:

• Click a category to see only its feeds.
• Click a single feed to read just that source.
• Click a list to read everything it bundles.

Reader mode (readable content)

Many feeds publish only a summary or stripped-down content. Folo's reader mode (also called Readability) re-fetches the original page and extracts the clean, full article — title, author, and body — stripping ads and clutter. On the desktop app this runs locally using Mozilla's Readability engine.

Read & unread

• Entries you've opened are marked read automatically.
• Use Mark all as read to clear a feed, list, category, or the whole view.
• The desktop dock/taskbar badge shows your total unread count and updates in the background.

Dynamic content

Folo renders content in place rather than bouncing you to a browser:

• Pictures display in a grid with a full-screen lightbox (zoom and pan).
• Videos play inline, including embedded players.
• Audios play in the built-in audio player with playback controls; mobile supports background/lock-screen playback.
• Code blocks are syntax-highlighted, with automatic language detection.
• Math renders via KaTeX.

Warning

Some embedded players (for example certain YouTube embeds) may show an anti-bot sign-in prompt inside the desktop webview. If a video won't play inline, open it in your external browser from the entry's context menu.

Save an article as PDF (desktop)

In the desktop app you can export the current article to a PDF file from the entry menu. Folo renders the clean reader view to PDF and prompts you for a save location.

8. AI Features

Folo has AI woven into reading. AI features call Folo's AI service by default; power users can bring their own model key.

Translation

Enable translation per-entry or set automatic translation in settings. Folo translates the relevant fields for each view — for example, title and content for articles, content for social posts.

Caution

A known issue exists where enabling automatic translation can cause article body text to disappear in reader mode for some content. If content vanishes after turning on auto-translate, toggle translation off for that entry as a workaround and watch the release notes for a fix.

Bring Your Own Key (BYOK)

In Settings → AI you can configure your own AI provider/model key instead of using Folo's hosted AI. This routes summary, translation, and chat through your provider.

Note

Model selection in the BYOK configuration is an area under active development; the set of selectable models depends on your provider and the current app version.

9. Organizing & Automating

Categories

Group subscriptions into categories within a view to keep large collections navigable. Assign a category when subscribing or change it later from the subscription's context menu (or via folo subscription update --category <name>).

Collections (starring)

Star any entry to add it to your Collections. Collections sync across devices and are a durable place to keep things you want to find again — independent of whether the source feed still has the entry.

Actions & automation

Folo's Actions let you define rules that run automatically on incoming entries. Typical uses include:

• Auto-notifications — get notified when entries match conditions (including pattern matching on titles/content).
• Auto-translation — translate matching entries automatically.
• Routing/marking — apply behavior to entries from specific feeds or matching filters.

Configure actions in Settings → Actions. Rules can use conditions to match a subset of entries.

Tip

For notification rules that match on text, conditions support pattern/regular-expression matching. Start with a simple keyword match and refine; test against a feed you know produces matching entries.

10. Integrations (Desktop)

The desktop app can hand entries off to local tools. Configure these in Settings → Integrations.

Note

Integrations run on your machine and talk to local services. They are only available in the desktop app, not the web or mobile clients.

11. The Folo CLI

The folo command brings your Folo account to the terminal. It's built for automation: every command prints a structured result you can pipe into scripts.

Authentication

The CLI reads a session token from three places, in priority order:

1. The --token <token> global flag
2. The FOLO_TOKEN environment variable
3. The stored config file at ~/.folo/config.json

# Sign in via your browser (opens a login page, captures the token)
folo login

# Or sign in with a one-time / session token from Folo
folo login --token <token>

folo login starts a tiny local callback server, opens your browser to the Folo login page, and exchanges the returned one-time token for a session token that it stores in ~/.folo/config.json. The config file holds your token and optional apiUrl.

Tip

If you use the desktop app, it automatically syncs its sign-in to the CLL config the first time both are present — you may already be logged in to folo without running folo login. Check with folo whoami.

folo whoami      # show the signed-in account, role, and quotas
folo logout      # clear the stored token

Global options

These apply to every command:

# Human-readable table instead of JSON
folo timeline --limit 5 --format table

Every successful command prints an envelope {"ok": true, "data": ..., "error": null}; failures print {"ok": false, "data": null, "error": {"code", "message"}} to stderr and exit non-zero — ideal for scripting.

--view values

Many commands accept --view to scope to a content type. Accepted values (name or number):

Command reference

folo auth

Manage CLI authentication.

folo login [--token <token>]    # browser sign-in or token exchange
folo logout                     # clear stored token
folo whoami                     # show current account

folo timeline

Read your unified timeline.

folo timeline --view articles --unread-only --limit 20

folo subscription

Manage subscriptions.

folo subscription list   [--view <type>] [--category <name>]
folo subscription add    --feed <url> | --list <listId> [--category <name>] [--view <type>] [--private] [--title <title>]
folo subscription remove ...
folo subscription update [--category <name>] [--title <title>] [--view <type>] [--private] [--public] [--target <feed|list>]

# Subscribe to a feed under a category, in the Articles view
folo subscription add --feed https://example.com/feed.xml --category Tech --view articles

folo entry

Work with individual entries.

folo entry get   <entryId>
folo entry read  <entryId>          # fetch readable (reader-mode) content
folo entry mark-read   <entryId>
folo entry mark-unread <entryId>
folo entry mark-all-read [--feed <feedId>] [--list <listId>] [--view <type>]

folo feed

Inspect feeds.

folo feed get      <feedId>
folo feed refresh  <feedId>
folo feed analytics <feedId>

folo list

Manage curated lists.

folo list (list|ls)
folo list get    <listId>
folo list create --description <text> [--view <type>] [--fee <amount>] [--image <url>]
folo list update <listId> [--title <t>] [--description <d>] [--view <type>] [--fee <amount>] [--image <url>]
folo list delete <listId>
folo list add-feed    <listId> <feedId>
folo list remove-feed <listId> <feedId>

folo opml

Import and export subscriptions.

folo opml export [--output <file>]         # write OPML (stdout or file)
folo opml import [--items <urls>]          # import a comma-separated list of feed URLs

folo search

Discover sources.

folo search discover --type <feeds|lists>
folo search rsshub   [--lang <lang>]
folo search trending [--category <keyword>] [--range <1d|3d|7d|30d>] [--view <type>] [--limit <n>] [--language <eng|cmn>]

folo collection

Manage your starred entries.

folo collection list  [--limit <n>] [--cursor <datetime>]
folo collection add    <entryId> [--view <type>]
folo collection remove <entryId>

folo unread

Check unread counts.

folo unread count
folo unread list [--view <type>]

Scripting example

# Print the 10 newest unread article headlines as plain text
folo timeline --view articles --unread-only --limit 10 --format plain

{
  ok: true,
  data: { entries: [ ... ], nextCursor: '2026-06-05T...', hasNext: true },
  error: null
}

Tip

Combine --format json with jq for powerful pipelines, e.g. folo timeline --limit 50 --format json | jq '.data.entries[].title'.

12. Settings Overview

Settings are organized into panes (available on desktop, web, and mobile, with platform-appropriate options):

Note

Your settings live with your account and the local app — there is no configuration file to edit by hand for normal use. Power-user and operator configuration is covered in the Admin Guide.

Proxy & network (desktop)

The desktop app lets you set a network proxy in settings — useful for accessing feeds behind a corporate or regional network boundary.

Cache management (desktop)

Folo caches article content and media for fast, offline-friendly reading. In settings you can set a cache size limit, clear the cache, and reveal the log file for troubleshooting. On Windows, clearing the cache may request elevation.

13. Keyboard Shortcuts & Command Palette

Folo's desktop and web clients are keyboard-friendly. The hub for everything is the command palette.

• Cmd/Ctrl + K — open the command palette. Type to find and run any command (switch views, add feeds, mark read, open settings, toggle AI, and more).

The command palette is modeled on VS Code's command system: actions are registered centrally and surfaced both in the palette and in context menus, so the same action is discoverable in multiple places. Navigation (next/previous entry, open, mark read) and common operations have dedicated shortcuts; browse them in Settings → Shortcuts.

Tip

When you don't remember a shortcut, you don't need to — open the command palette and search by name. The action's bound shortcut (if any) is shown next to it.

14. Troubleshooting

Folo prints clear errors and the team tracks issues publicly. Below are the most common problems and fixes, drawn from real reported issues.

Error: Missing token. Run \folo login` ...`

Cause: The CLI has no session token. Solution: Run folo login, set FOLO_TOKEN, or pass --token. If you use the desktop app, confirm the CLI is connected in Settings → CLI. Prevention: Keep the desktop app signed in; it syncs the token to the CLI.

Error: UNAUTHORIZED (CLI) / "Token is invalid or expired"

Cause: The stored token expired or was revoked. Solution: Run folo logout then folo login again. Prevention: Re-authenticate periodically; sessions don't last forever.

The mobile client fails to log in

Cause: OAuth/redirect handling can fail on some mobile network or OS configurations. Solution: Retry sign-in; switch networks (e.g. off VPN); ensure the app is updated. On iOS, if a system-level sign-in won't complete, try email/password sign-in. Prevention: Keep the app at the latest version.

Desktop OAuth sign-in doesn't complete

Cause: The in-app login window can't finish the OAuth handshake. Solution: Sign in at app.folo.is, copy the __Secure-better-auth.session_token cookie, and paste it into the desktop app's manual token entry. Prevention: Keep the app updated.

Captcha / "Captcha verification failed"

Cause: Anti-abuse verification during sign-up or sensitive actions. Solution: Complete the captcha challenge; retry; ensure your clock is correct and you aren't on a flagged network. Prevention: Avoid VPNs/proxies during sign-up if verification keeps failing.

Text-to-speech (TTS) isn't working

Cause: TTS depends on Folo's TTS service (tts.folo.is); transient service or network issues can break playback. Solution: Check your connection, retry, and update the app. If a specific voice fails, try another voice. Prevention: Keep the app updated; the team tracks TTS reliability.

Auto-translation hides article content

Cause: A known interaction between automatic translation and reader mode can blank the content area for some entries. Solution: Turn off auto-translation for the affected entry/feed as a workaround. Prevention: Use per-entry translation until a fix ships.

Embedded video shows an anti-bot / sign-in message

Cause: Some sites (e.g. YouTube) block embedded playback in the desktop webview. Solution: Open the entry in your external browser from the entry's context menu. Prevention: None app-side; this is enforced by the upstream site.

Inbox isn't receiving forwarded emails

Cause: Forwarding to your Folo inbox address may be delayed, mis-addressed, or filtered. Solution: Verify you're sending to the exact inbox address from Settings → Inbox; allow time for delivery; check that the sending service isn't bouncing. Prevention: Send a test email to confirm the address works before relying on it.

Desktop app runs hot / high CPU (e.g. on Apple Silicon)

Cause: Heavy rendering (large image/video feeds, many animations) can drive CPU/GPU usage up. Solution: Reduce open media-heavy views, lower visual effects in Appearance, and keep the app updated; performance fixes ship regularly. Prevention: Prefer the Articles view for bulk reading; reserve Pictures/Videos grids for active browsing.

Clearing space / stale content

Cause: The local cache grew large or holds stale media. Solution (desktop): Settings → Data & cache → Clear cache, or set a cache size limit. Use Reveal log file when reporting bugs. Prevention: Set a sensible cache limit.

15. Frequently Asked Questions

Q: Is Folo free? Yes. All clients are free and open source under AGPL-3.0. Some membership tiers and paid lists exist, but core reading is free.

Q: Do I need to self-host anything? No. Folo is a hosted product — sign in and go. (Developers can run it from source; see the Admin Guide.)

Q: Where is my data stored? Your subscriptions, read state, and collections are synced to your Folo account. Clients also keep a local database/cache for speed and offline reading.

Q: Can I import from Feedly / Inoreader / another reader? Yes — export an OPML file from your old reader and import it via Settings → Subscriptions → Import or folo opml import.

Q: What's the difference between a feed and a list? A feed is one source. A list is a curated bundle of feeds someone publishes; subscribing to a list follows all of them at once.

Q: Why are my tweets/photos/videos in separate tabs? Folo uses views to keep content types from drowning each other. Switch views with the tabs, or use All to merge everything.

Q: What is RSSHub and why does Folo use it? RSSHub generates feeds for sites that don't publish their own. Folo's Discover screen lets you browse RSSHub routes by category and subscribe to them like any other feed.

Q: Can I read offline? Largely yes on desktop and mobile — cached entries and media remain available. New content requires a connection to sync.

Q: How do I get a clean, full-text version of a truncated feed? Use reader mode (Readability) on the entry, or folo entry read <entryId> from the CLI.

Q: Does the CLI need the desktop app? No, but it cooperates with it. The CLI works standalone with folo login; if the desktop app is installed and signed in, it can share its session with the CLI automatically.

Q: What output formats does the CLI support? json (default, scripting-friendly), table (human-readable ASCII), and plain.

Q: Can I run AI features with my own API key? Yes — configure Bring Your Own Key in Settings → AI.

Q: How do I save an article to Obsidian? On desktop, set your vault path in Settings → Integrations → Obsidian, then use the entry's Save to Obsidian action. Folo writes a Markdown note with frontmatter.

Q: How do I report a bug or request a feature? Open an issue on the GitHub repository or join the Discord.

Q: How do I get notified about new releases? Star the repository on GitHub to receive release notifications, or follow @folo_is.