# 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.

| Version | Best for | Highlights |
|---------|----------|------------|
| **Web** (`app.folo.is`) | Trying instantly, any OS | Nothing to install; full reading experience in the browser |
| **Desktop** (Electron) | Daily heavy reading | Tray + dock unread badge, system notifications, offline cache, "Save to PDF", local integrations (Obsidian/Eagle/qBittorrent), CLI session sync |
| **Mobile** (iOS/Android) | Reading on the go | Native gestures, background refresh, push notifications, audio player, share-sheet |
| **CLI** (`folo`) | Automation & scripting | Read your timeline, manage subscriptions, import/export OPML, query unread counts — all as JSON/table/plain text |

> [!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](https://app.folo.is) in any browser, or install
   the desktop/mobile app (see [Installation](#3-installation)).
2. **Create an account or sign in.** Use Google, GitHub, or Apple, or register with an
   email and password. See [Accounts & Sign-In](#4-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.

```text
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 <kbd>Cmd/Ctrl</kbd> + <kbd>K</kbd> 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](https://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](https://apps.apple.com/us/app/folo-follow-everything/id6739802604).
    - **Direct download** — grab the `.dmg` from the
      [GitHub Releases](https://github.com/RSSNext/Folo/releases/latest) page.
    - **Homebrew** (community-maintained):

        ```bash
        brew install --cask folo
        ```

=== "Windows"

    - **Microsoft Store** —
      [open the listing](https://apps.microsoft.com/detail/9nvfzpv0v0ht?mode=direct).
    - **Direct download** — grab the installer from
      [GitHub Releases](https://github.com/RSSNext/Folo/releases/latest).
    - **Scoop** (community-maintained manifest `folo`).

=== "Linux"

    - **Direct download** — grab the AppImage from
      [GitHub Releases](https://github.com/RSSNext/Folo/releases/latest).
    - **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](https://apps.apple.com/us/app/folo-follow-everything/id6739802604).

=== "Android"

    - **Google Play** —
      [open the listing](https://play.google.com/store/apps/details?id=is.follow).
    - **Direct APK** — download from
      [GitHub Releases](https://github.com/RSSNext/Folo/releases/latest).

> [!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.

```bash
# Run without installing
npx folocli@latest --help

# Or install globally
npm install -g folocli
```

```text
Usage: folo [options] [command]

Folo CLI client for structured automation
```

The CLI requires **Node.js 18 or newer**. See [The Folo CLI](#11-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

| Method | How |
|--------|-----|
| **Google** | One-click OAuth |
| **GitHub** | One-click OAuth |
| **Apple** | One-click OAuth (and native Sign in with Apple on iOS/macOS) |
| **Email + password** | Register with name, email, and password, then sign in |

### 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](https://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:

| Role | Notes |
|------|-------|
| **Free** | Default tier for new accounts |
| **Basic** / **Plus** / **Pro** | Higher subscription limits and member features |
| **Admin** | Platform staff |

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:

| View | Icon meaning | Typical content |
|------|--------------|-----------------|
| **All** | Everything combined | Every subscription, merged |
| **Articles** | Long-form | Blogs, news, newsletters |
| **Social Media** | Short posts | Microblogs, timelines (wide layout) |
| **Pictures** | Images | Photo feeds, galleries (grid layout) |
| **Videos** | Video | YouTube-style and video feeds (grid layout) |
| **Audios** | Audio | Podcasts and audio feeds |
| **Notifications** | Alerts | Sources you want as notifications |

**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:

```bash
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](#11-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.

| Feature | What it does |
|---------|--------------|
| **Summary** | Generates a concise summary of an article so you can triage quickly |
| **Translation** | Translates entry content into your preferred language |
| **AI Chat** | Opens a chat side-panel where you can ask questions about the entry or your feeds, with a rich editor (mentions, file upload, shortcuts) |
| **AI tasks / actions** | Run AI-assisted operations as part of automation |

### 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**.

| Integration | What it does | Notes |
|-------------|--------------|-------|
| **Obsidian** | Save an article to your vault as a Markdown note with YAML frontmatter (url, author, publishedAt, tags, feed info) | Choose your vault path; filenames are sanitized; duplicate filenames are skipped |
| **Eagle** | Save images/media from an entry to the Eagle app | Requires Eagle running locally (listens on `localhost:41595`); can add a right-click context-menu item |
| **qBittorrent** | Send magnet links from an entry to your qBittorrent instance | Provide host, username, and password; Folo authenticates and adds the magnet(s) |
| **Custom URL scheme** | Open a custom `app://`-style URL with the entry | Useful for handing off to other apps |
| **Custom fetch** | Advanced: make a configurable HTTP request as part of an integration | Sensitive headers/params are masked in logs |

> [!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`

```bash
# 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`.

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

### Global options

These apply to every command:

| Option | Description | Default |
|--------|-------------|---------|
| `-f, --format <format>` | Output format: `json`, `table`, or `plain` | `json` |
| `--api-url <url>` | Override the API base URL | `https://api.folo.is` |
| `--token <token>` | Override the stored token | — |
| `--verbose` | Log every request/response to stderr | off |

```bash
# 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):

| Value | Number |
|-------|--------|
| `articles` (or `article`) | `0` |
| `social` (or `socialmedia`) | `1` |
| `pictures` (or `picture`) | `2` |
| `videos` (or `video`) | `3` |
| `audio` | `4` |
| `notifications` (or `notification`) | `5` |

### Command reference

#### `folo auth`

Manage CLI authentication.

```bash
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.

| Option | Description |
|--------|-------------|
| `--view <type>` | Scope to a view |
| `--limit <n>` | Number of entries to fetch |
| `--unread-only` | Only unread entries |
| `--cursor <datetime>` | Pagination cursor (entries published after) |
| `--feed <feedId>` | Filter to one feed |
| `--list <listId>` | Filter to one list |
| `--category <name>` | Filter to one subscription category |

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

#### `folo subscription`

Manage subscriptions.

```bash
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>]
```

```bash
# 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.

```bash
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.

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

#### `folo list`

Manage curated lists.

```bash
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.

```bash
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.

```bash
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.

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

#### `folo unread`

Check unread counts.

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

### Scripting example

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

```text
{
  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):

| Pane | What you control |
|------|------------------|
| **Account** | Profile, sign-in methods, 2FA, role/quota |
| **General** | Language, startup behavior, launch-at-login (desktop), minimize-to-tray (desktop) |
| **Appearance** | Light/dark/system theme, fonts, layout density, content rendering |
| **Reading / Feeds** | Default view behavior, mark-as-read rules, content display |
| **AI** | AI features, automatic translation, Bring Your Own Key |
| **Actions** | Automation rules (notifications, auto-translate, filters) |
| **Integrations** (desktop) | Obsidian, Eagle, qBittorrent, custom |
| **Lists** | Lists you own or manage |
| **CLI** (desktop) | Connect/disconnect the `folo` CLI to your desktop session |
| **Data & cache** (desktop) | Cache size limit, clear cache, reveal log file |
| **Notifications** | Push and in-app notification preferences |

> [!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**.

- <kbd>Cmd/Ctrl</kbd> + <kbd>K</kbd> — 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](https://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](https://github.com/RSSNext/Folo/issues) or join the
[Discord](https://discord.gg/AwWcAQ7euc).

**Q: How do I get notified about new releases?**
Star the repository on GitHub to receive release notifications, or follow
[@folo_is](https://x.com/intent/follow?screen_name=folo_is).

---

_Generated June 2026 from RSSNext/Folo at c98f572. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._