AppFlowy User Guide

AppFlowy is an open-source, privacy-first workspace for notes, tasks, databases, and wikis. It runs on macOS, Windows, Linux, iOS, Android, and the web, keeping your data local by default with optional cloud sync and real-time collaboration through AppFlowy Cloud. This guide covers every feature and workflow you need to be productive with AppFlowy version 0.11.4.

1. Quick Start

Your first five minutes

1. Download AppFlowy from appflowy.io for your platform.
2. Launch the application. You land on a welcome screen.
3. Choose your sign-in method: sign in as Guest (fully local, no account needed), or authenticate with Google OAuth or email/password through AppFlowy Cloud.
4. Create your first page: click the + New Page button in the sidebar. A blank document opens instantly.
5. Start typing: click anywhere in the document body. Use Markdown shortcuts as you type or highlight text to reveal the formatting toolbar.

Key concepts

Tip

Sign in as Guest to explore AppFlowy without creating an account. You can migrate to cloud sync later by signing in with Google or email from Settings.

2. Installation

2.1 macOS

Supported architectures: Apple Silicon (arm64) and Intel (x86_64). Minimum deployment target: macOS 11.0 (Big Sur).

1. Download the .dmg file from the AppFlowy releases page.
2. Open the .dmg and drag AppFlowy into your Applications folder.
3. On first launch, macOS may warn about an unidentified developer. Open System Preferences > Security & Privacy and click Open Anyway.
4. AppFlowy launches and presents the authentication screen.

2.2 Windows

Supported architecture: x86_64. Windows 10 and later.

1. Download the .exe installer or .zip portable archive from the releases page.
2. Installer: run the .exe, follow the wizard, and launch from the Start Menu.
3. Portable: extract the .zip to any folder, then run AppFlowy.exe.

Warning

Version 0.11.4 has a known issue (#8577) where the app may crash on fresh install on Windows 10. If you experience this, try running AppFlowy as Administrator for the initial launch, or install the latest patch release.

2.3 Linux

Supported architectures: x86_64 (primary), aarch64 (production builds available).

Option A — Install script:

curl -fsSL https://appflowy.io/install.sh | bash -s

The install.sh script downloads the latest release archive and installs to /opt by default. Flags:

Example with custom directory:

curl -fsSL https://appflowy.io/install.sh | bash -s -- -b ~/.local/bin 0.11.4

Option B — AppImage:

1. Download the .AppImage from the releases page.
2. Make it executable: chmod +x AppFlowy-*.AppImage
3. Run: ./AppFlowy-*.AppImage

Option C — Snap Store:

AppFlowy is available on the Snap Store, though some users have reported issues opening the snap package (see Troubleshooting, #8659).

Important

On Linux, AppFlowy requires several shared libraries. If you see error while loading shared libraries: libvdpau.so.1 (issue #8655), install the VDPAU library for your distribution:

• Ubuntu/Debian: sudo apt install libvdpau1
• Fedora: sudo dnf install libvdpau
• Arch: sudo pacman -S libvdpau

2.4 iOS

1. Open the App Store on your iPhone or iPad.
2. Search for AppFlowy.
3. Tap Get and authenticate with Face ID, Touch ID, or your Apple ID password.

Requires iOS 15.0 or later. ARM64 only.

2.5 Android

1. Open Google Play on your device.
2. Search for AppFlowy and tap Install.

Minimum SDK: Android 10 (API level 29). Target SDK: Android 15 (API level 35). Architecture: arm64-v8a.

2.6 Web

Access AppFlowy directly in your browser at app.appflowy.io (requires AppFlowy Cloud account). No installation necessary. Feature parity is close to the desktop experience but some offline and local-storage features are limited to native apps.

2.7 Updating AppFlowy

AppFlowy checks for updates on launch. When a new version is available, a notification appears. Click it to download and install the update. On Linux with the install script, re-run the same command to upgrade in place.

Note

Custom themes may be lost after an app update (issue #8663). Export your custom theme JSON before updating and re-import it afterward. See the Customization section for details.

2.8 Uninstalling

3. Configuration

3.1 Authentication and cloud setup

AppFlowy supports three authentication modes:

Signing in with Google:

1. Click Sign in with Google on the auth screen.
2. A browser window opens for OAuth. Authorize AppFlowy.
3. Return to the app. Your workspace syncs automatically.

Signing in with email/password:

1. Click Sign in with email.
2. Enter your email and password (accounts managed by GoTrue on AppFlowy Cloud).
3. If you do not have an account, click Sign Up to create one.

Switching cloud type: Navigate to Settings > Cloud Settings. The kCloudType setting determines which backend AppFlowy connects to. Options include AppFlowy Cloud (default) or a self-hosted instance. For self-hosted, set the base URL (kAppflowyCloudBaseURL) to your server address.

Caution

Restarting cloud services while in offline mode can cause data loss (issue #8635). Always ensure you have a stable connection before switching between cloud providers or restarting sync. Back up your local data directory before making cloud configuration changes.

3.2 Data storage location

By default, AppFlowy stores data locally on your device. The storage path is configurable:

1. Open Settings > Files.
2. View or change the Data Path (pathLocation).
3. Restart AppFlowy for changes to take effect.

Default locations:

• macOS: ~/Library/Application Support/AppFlowy/
• Windows: %APPDATA%\AppFlowy\
• Linux: ~/.appflowy/

3.3 Appearance and editor settings

Navigate to Settings > Appearance to configure:

3.4 Window behavior

AppFlowy remembers your window state across sessions:

• Window size (windowSize) and position (windowPosition) are automatically saved.
• Maximized state (windowMaximized) is restored on launch.

3.5 Notification settings

Toggle the notification icon in the sidebar via the showNotificationIcon setting. When enabled, you receive in-app notifications for collaboration events, mentions, and reminders.

3.6 Compact mode

Individual views can be set to compact mode using the view menu, storing preferences in compactModeIds. Compact mode reduces spacing and padding for denser information display, particularly useful for database grids with many rows.

3.7 Feature flags

Advanced or experimental features are gated behind feature flags (featureFlag). These are typically managed by the development team and are not exposed in the standard settings UI. Power users building from source may toggle these in the configuration.

For full configuration reference, cloud deployment options, and self-hosting setup, see the AppFlowy Admin Guide.

4. Core Usage

4.1 Workspace and space management

Understanding the hierarchy

Workspace
  └── Space (e.g., "Personal", "Work")
       └── Page (Document, Grid, Board, Calendar)
            └── Subpage (nested under any page)

Creating a space

1. In the sidebar, click the + icon next to your workspace name.
2. Choose New Space.
3. Give it a name (e.g., "Product Roadmap", "Personal Notes").
4. The space appears in the sidebar. Drag pages into it or create new ones inside.

Sidebar navigation

The sidebar is your command center:

• Favorites: pinned pages for quick access (star icon on any page).
• Recent: automatically tracks your most recently visited pages.
• Spaces: your organizational containers.
• Trash: deleted pages live here for recovery before permanent deletion.

The sidebar remembers which folders are expanded (expandedFolders) and which views are expanded (expandedViews) across sessions.

Favorites

Right-click any page and select Add to Favorites, or click the star icon in the page header. Favorited pages appear in the Favorites section at the top of the sidebar for one-click access.

Recent views

The Recent section shows your most recently opened pages in chronological order. This updates automatically — no action needed.

Trash management

1. Delete a page by right-clicking it in the sidebar and selecting Delete, or pressing Delete/Backspace when the page is selected.
2. The page moves to Trash in the sidebar.
3. Open Trash to see all deleted pages with timestamps.
4. Restore: click the restore icon to return the page to its original location.
5. Permanently delete: click the delete icon. This action cannot be undone.
6. Empty Trash: permanently remove all trashed items at once.

4.2 Document editing

AppFlowy's document editor is a block-based rich text editor with Markdown-style shortcuts. Every piece of content in a document is a "block" — a paragraph, heading, list item, code block, image, or other element.

Getting started with a document

1. Click + New Page in the sidebar or the + icon next to any existing page title.
2. Choose Document as the page type.
3. Click anywhere in the body and start typing.

Text formatting

Inline formatting — highlight any text to reveal the formatting toolbar:

Block-level formatting — type at the beginning of a line:

The slash command menu

Type / anywhere in a document to open the slash command menu. This is the fastest way to insert any content block:

Code blocks

1. Type /code and press Enter, or use the Markdown shortcut ```.
2. A code block appears with a language selector dropdown at the top.
3. Click the language selector to choose syntax highlighting (Python, JavaScript, Rust, Dart, Go, C++, and many more).
4. Type or paste your code. Syntax highlighting applies automatically.

def hello():
    print("Code blocks support syntax highlighting")

Images and media

Inserting images:

1. Type /image or drag-and-drop an image file into the document.
2. Choose from: Upload (from your device), URL (paste a link), or Unsplash (search stock photos).
3. Resize by dragging the handles on the image corners.

File uploads:

1. Type /file to insert a file block.
2. Upload any file type. The file is stored locally or in AppFlowy Cloud (if connected).
3. Other collaborators can download the file from the cloud-synced document.

Tables

1. Type /table to insert a table.
2. Specify initial rows and columns.
3. Click any cell to edit its content.
4. Use the row/column controls (visible on hover) to add, delete, or reorder rows and columns.
5. Tables support inline formatting within cells.

Math equations

1. Type /math to insert a math equation block.
2. Enter LaTeX syntax in the editor.
3. The equation renders in real-time below the input.

Example: E = mc^2 renders as the familiar mass-energy equivalence equation.

Toggle lists

1. Type /toggle to create a collapsible section.
2. Add a title to the toggle header.
3. Indent content below it — everything indented becomes the collapsible body.
4. Click the arrow to expand/collapse.

Toggle lists are excellent for FAQs, long reference sections, or hiding detailed notes.

Callout blocks

1. Type /callout to insert a highlighted callout.
2. Choose an icon (emoji) to set the callout's visual indicator.
3. Type your message. Callouts support full rich text formatting inside.

Mentions and references

• Page mention: type @ followed by a page name to insert a clickable reference to another page.
• Date mention: type /date to insert a date stamp. Click it to select a specific date.
• Person mention: in collaborative workspaces, type @ followed by a team member's name.

Outline / table of contents

Type /outline to insert an auto-generated table of contents block. It lists all headings in the current document and updates as you add or modify headings. Clicking an entry scrolls to that heading.

Keyboard shortcuts reference

4.3 Databases

Databases in AppFlowy let you organize structured information with multiple visualization options. A single database can be viewed simultaneously as a Grid, Kanban Board, or Calendar.

Creating a database

As a standalone page:

1. Click + New Page in the sidebar.
2. Choose Grid, Board, or Calendar.
3. The database opens with a default view.

Inline within a document:

1. In any document, type /grid, /board, or /calendar.
2. An inline database appears within the document body.

As a subpage:

1. Hover over an existing page in the sidebar.
2. Click the + icon.
3. Choose Grid, Kanban Board, or other view type.

Grid view

The grid is a spreadsheet-like table with rows and columns:

• Adding rows: click the + button at the bottom of the grid, or press Enter from the last row.
• Adding fields (columns): click the + at the right edge of the column headers.
• Reordering columns: drag a column header to rearrange.
• Resizing columns: drag the border between column headers.
• Row details: click any row's expand icon to open a full-page detail view with all fields.

Kanban board view

The Kanban board groups rows into columns based on a Single Select or Multi-Select field:

• Moving cards: drag cards between columns to update their status/category.
• Creating cards: click + at the bottom of any column.
• Configuring groups: the board groups by a selected field. Change the grouping field in view settings.
• Card preview: cards can show a preview of key fields (title, date, cover image).

Calendar view

The calendar displays database rows based on a Date field:

• Navigation: use the arrows to move between months.
• Creating events: click on any date cell to create a new row with that date pre-filled.
• Viewing events: click an event on the calendar to open its row detail.
• Date field selection: choose which date field the calendar uses for positioning in view settings.

Field types

Each column/field in a database has a type that determines what data it holds and how it behaves:

Changing field type:

1. Click a column header.
2. Select Edit field.
3. Change the Type dropdown. Data is converted where possible (e.g., text to number).

Configuring Select/Multi-Select options:

1. Click the field header and choose Edit field.
2. Add, rename, reorder, or color-code options.
3. Colors help visually distinguish categories in all views.

Filters

Filters let you show only rows matching specific criteria:

1. Click the Filter icon in the database toolbar.
2. Click Add Filter.
3. Choose a field, an operator (is, is not, contains, does not contain, is empty, is not empty, etc.), and a value.
4. Multiple filters combine with AND logic.
5. Filters are per-view — each Grid, Board, or Calendar view maintains its own filters independently.

Examples:

• Show only rows where Status is "In Progress"
• Show rows where Due Date is before 2026-06-01
• Show rows where Assignee is not empty

Sorts

Order rows by one or more fields:

1. Click the Sort icon in the database toolbar.
2. Click Add Sort.
3. Choose a field and direction (ascending or descending).
4. Add multiple sorts for tie-breaking (e.g., sort by Priority descending, then by Date ascending).
5. Drag to reorder sort priority.
6. Sorts are per-view.

Groups (Kanban)

In Kanban board view, rows are grouped by a Select or Multi-Select field:

1. Open the Board view settings.
2. Choose the Group by field.
3. Each option value becomes a column.
4. Rows without a value for the group field appear in a "No Status" column.

Row covers

Add a visual cover to any database row:

1. Open the row detail view (click the expand icon on any row).
2. Click Add Cover at the top.
3. Choose an image from your uploads, Unsplash, or a solid color.
4. The cover displays as a banner in the row detail and as a preview on Kanban cards.

CSV export

Export any database view to CSV:

1. Click the ... menu in the database toolbar.
2. Select Export to CSV.
3. Choose a save location. The CSV includes all visible columns and rows (respecting current filters).

Multiple views on one database

A single database can have multiple views with different types, filters, sorts, and visible fields:

1. In the database header, click the + tab icon.
2. Choose a view type (Grid, Board, or Calendar).
3. Name the new view.
4. Configure independent filters, sorts, field visibility, and grouping.
5. Switch between views using the tabs at the top of the database.

This is powerful for workflows: the same task database can show a full grid for detail work, a Kanban board for sprint planning, and a calendar for deadline tracking.

4.4 AI features

AppFlowy integrates AI capabilities for content generation, summarization, and conversational assistance. AI features are available through AppFlowy Cloud or can be configured to use a local model via Ollama.

AI text completion

1. Select text in a document.
2. The formatting toolbar includes AI actions:
   • Improve Writing: refines grammar, clarity, and tone.
   • Fix Spelling & Grammar: corrects errors.
   • Summarize: condenses the selected text.
   • Translate: translates to a chosen language.
   • Make Longer / Shorter: expands or condenses content.
   • Continue Writing: generates a continuation from the selected text.
3. The AI-generated result appears inline. Accept, discard, or regenerate.

AI chat

1. Open the AI chat panel (available from the toolbar or sidebar).
2. Type a question or prompt.
3. The AI responds conversationally with context from your workspace.
4. Use AI chat for brainstorming, research, content drafting, or quick answers.

Using a local AI model (Ollama)

For users who prefer fully local AI processing:

1. Install Ollama on your machine.
2. Pull a model: ollama pull llama3 (or another supported model).
3. In AppFlowy Settings > AI Settings, select Local AI and configure the Ollama endpoint.
4. AI features now run entirely on your hardware with no data sent to external servers.

Tip

Local AI via Ollama is ideal for sensitive documents or air-gapped environments. Performance depends on your hardware — a GPU with at least 8GB VRAM is recommended for responsive completions.

4.5 Search

AppFlowy includes full-text search powered by the Tantivy search engine, providing fast results across all your content.

Using search

1. Press Ctrl/Cmd + P or click the search icon in the sidebar.
2. Type your query.
3. Results appear instantly, showing matching pages and the context around each match.
4. Click a result to navigate directly to that page.

Search indexes document content, page titles, and database content. Results update as you type, and the index refreshes as you edit content.

4.6 Publishing and sharing

Publishing a page

1. Open the page you want to share.
2. Click the Share button in the top-right toolbar.
3. Toggle Publish on.
4. A public URL is generated using the share domain (kAppFlowyBaseShareDomain).
5. Anyone with the link can view the published page — no AppFlowy account required.

Sharing with collaborators

With AppFlowy Cloud:

1. Open the page or workspace.
2. Click Share.
3. Enter collaborators' email addresses.
4. Set permissions (view, edit).
5. Collaborators see the shared content in their workspace after accepting the invitation.

4.7 Real-time collaboration

When connected to AppFlowy Cloud, multiple users can edit the same document or database simultaneously:

• Cursor presence: see other users' cursors and selections in real-time, each in a distinct color.
• Conflict resolution: AppFlowy uses CRDT (Conflict-free Replicated Data Types) via the Collab engine to merge concurrent edits without conflicts.
• Offline editing: changes made offline are queued locally and automatically merged when you reconnect.

Collaboration works across all content types — documents, grids, boards, and calendars.

4.8 Import and export

Importing content

AppFlowy supports importing from various formats:

1. Click the ... menu in the sidebar or use the import option from Settings.
2. Supported import sources include Markdown files and other structured formats.
3. Imported content is created as new pages in your current space.

Exporting content

Export individual pages or databases:

1. Open the page.
2. Click the ... menu in the page header.
3. Choose the export format:
   • Markdown — preserves formatting as Markdown syntax.
   • JSON — structured data export.
   • CSV — for database views (see Database section).
4. Choose a save location.

5. Common Tasks

5.1 Workflow recipes: document workflows

Recipe: meeting notes template

1. Create a new document page named "Meeting Notes — [Date]".
2. Add a Heading 2: "Attendees", then a bulleted list of participants.
3. Add a Heading 2: "Agenda", then a numbered list of topics.
4. Add a Heading 2: "Discussion", with toggle lists for each agenda item (expand for details, collapse for overview).
5. Add a Heading 2: "Action Items", then to-do checkboxes with assignee mentions (@name) and due dates.
6. Add a Heading 2: "Next Meeting", with a date mention.
7. Favorite the page for quick access before each meeting.

Recipe: knowledge base wiki

1. Create a Space called "Knowledge Base".
2. Create a top-level page "Index" with an outline block.
3. Create subpages for each topic: "Onboarding", "Engineering Standards", "Design System", etc.
4. In each subpage, use Heading 2 and Heading 3 to organize sections.
5. Use callout blocks for important warnings or policy statements.
6. Add @page mentions to cross-reference between articles.
7. Publish the Index page to share externally.

Recipe: daily journal

1. Create a Space called "Journal".
2. Each day, create a new page with the date as the title.
3. Use a consistent structure:
   • Heading 2: "Priorities" — to-do checkboxes for the day.
   • Heading 2: "Notes" — free-form thoughts, meeting recaps.
   • Heading 2: "End-of-Day Review" — toggle list summarizing accomplishments.
4. Use the search function (Ctrl/Cmd + P) to find entries by keyword.

Recipe: technical documentation

1. Create a document page with the project name as the H1 title.
2. Insert an /outline block at the top for auto-generated table of contents.
3. Use Heading 2 for major sections: "Architecture", "Setup", "Deployment".
4. Insert code blocks with language selection for configuration snippets and examples.
5. Use tables for reference data (environment variables, endpoints, ports).
6. Use callout blocks for prerequisites, warnings, and version-specific notes.
7. Insert images for architecture diagrams (drag-and-drop or /image).

Recipe: writing a long-form article

1. Create a document and draft an outline using toggle lists for each section.
2. Expand each toggle and write the first draft.
3. Select sections and use AI > Improve Writing to refine tone and clarity.
4. Use AI > Make Shorter on verbose paragraphs.
5. Add a /divider between major sections for visual separation.
6. Insert a /outline block at the top as a table of contents.
7. Publish when ready.

5.2 Workflow recipes: database workflows

Recipe: project task tracker

1. Create a new Grid page called "Project Tasks".
2. Add fields:
   • Title (Text) — task name.
   • Status (Select) — options: "To Do", "In Progress", "Review", "Done".
   • Priority (Select) — options: "Critical", "High", "Medium", "Low".
   • Assignee (Text) — team member name.
   • Due Date (Date) — deadline.
   • Estimated Hours (Number) — effort estimate.
   • Notes (Text) — additional context.
3. Add a Board view tab grouped by Status. Drag cards between columns as tasks progress.
4. Add a Calendar view tab using Due Date. Visualize deadlines at a glance.
5. Create filters: "My Tasks" (Assignee is "your name"), "Overdue" (Due Date is before today, Status is not "Done").

Recipe: CRM / contact database

1. Create a Grid page called "Contacts".
2. Add fields:
   • Name (Text)
   • Company (Text)
   • Email (URL)
   • Phone (Text)
   • Status (Select) — "Lead", "Active", "Churned"
   • Last Contact (Date)
   • Notes (Text)
3. Sort by Last Contact ascending to surface contacts you haven't reached out to recently.
4. Filter by Status "Lead" for a prospecting view.

Recipe: content calendar

1. Create a database called "Content Calendar".
2. Add fields:
   • Title (Text) — post/article name.
   • Type (Select) — "Blog", "Social", "Newsletter", "Video".
   • Publish Date (Date).
   • Status (Select) — "Idea", "Drafting", "Review", "Published".
   • Author (Text).
   • Channel (Multi-Select) — "Twitter", "LinkedIn", "Website".
3. Create a Calendar view using Publish Date.
4. Create a Board view grouped by Status.
5. Filter the Grid view by current month for a focused list.

Recipe: bug tracker

1. Create a database called "Bug Tracker".
2. Add fields:
   • Bug Title (Text)
   • Severity (Select) — "Critical", "Major", "Minor", "Cosmetic"
   • Status (Select) — "New", "Investigating", "Fix in Progress", "Resolved", "Closed"
   • Reported By (Text)
   • Reported Date (Date)
   • Assigned To (Text)
   • Steps to Reproduce (Text)
   • Resolution (Text)
3. Board view grouped by Status for triage.
4. Grid view sorted by Severity descending, then Reported Date ascending.
5. Filter: "Open Bugs" = Status is not "Resolved" and Status is not "Closed".

Recipe: reading list / media tracker

1. Create a database called "Reading List".
2. Add fields:
   • Title (Text)
   • Author (Text)
   • Status (Select) — "Want to Read", "Reading", "Finished"
   • Rating (Number) — 1-5
   • Date Finished (Date)
   • Notes (Text)
   • Genre (Multi-Select) — "Fiction", "Non-Fiction", "Technical"
3. Board view grouped by Status.
4. Grid view with filter: Rating is greater than 3 (your favorites).

Recipe: inventory or asset tracker

1. Create a database called "Inventory".
2. Add fields:
   • Item (Text)
   • Category (Select) — "Electronics", "Furniture", "Supplies"
   • Quantity (Number)
   • Location (Text)
   • Purchase Date (Date)
   • Serial Number (Text)
   • Photo (Media)
3. Use row covers with the Photo field for visual identification.
4. Filter by Category for focused views.

Recipe: habit tracker

1. Create a database called "Habits".
2. Add fields:
   • Habit (Text) — e.g., "Exercise", "Read 30 min", "Meditate"
   • Monday through Sunday (Checkbox each)
   • Streak (Number) — manually tracked or calculated
3. Each week, add a new row per habit or duplicate last week's template.
4. Checklist fields also work well here — add each day's activity as sub-items.

Recipe: sprint planning board

1. Create a database called "Sprint Board".
2. Add fields:
   • Story (Text)
   • Sprint (Select) — "Sprint 1", "Sprint 2", etc.
   • Status (Select) — "Backlog", "To Do", "In Progress", "Testing", "Done"
   • Points (Number) — story points
   • Assignee (Text)
   • Epic (Select) — high-level grouping
3. Board view grouped by Status, filtered by current Sprint.
4. Grid view sorted by Points descending to prioritize high-effort items.

Recipe: using database relations

1. Create two databases: "Projects" and "Tasks".
2. In the "Tasks" database, add a Relation field pointing to "Projects".
3. When editing a task row, click the Relation field and select the associated project.
4. This creates a two-way link: the project's row detail shows all related tasks.
5. Use this pattern for any parent-child or many-to-many relationship: Clients-to-Projects, Courses-to-Lessons, Departments-to-Employees.

5.3 Workflow recipes: workspace management

Recipe: organizing a team workspace

1. Create Spaces for each team or function: "Engineering", "Design", "Marketing".
2. Within each Space, create key pages:
   • A wiki/knowledge base (document with subpages).
   • A task database (grid + board + calendar views).
   • A meeting notes section (document with dated subpages).
3. Share each Space with the relevant team members via AppFlowy Cloud.
4. Set page-level permissions where needed (some pages view-only, others editable).

Recipe: personal dashboard

1. Create a document page called "Dashboard".
2. Add inline databases:
   • /grid linked to your task database (filtered to "My Tasks", Status is not "Done").
   • /calendar linked to your content calendar (current month).
3. Add text sections with links to frequently accessed pages.
4. Favorite the Dashboard page for instant access.

Recipe: moving from Guest to Cloud

1. Open Settings > Cloud Settings.
2. Sign in with Google OAuth or email/password.
3. Your local data is uploaded to AppFlowy Cloud.
4. Collaboration features, publishing, and cross-device sync become available.
5. Local data remains on your device as a cache for offline access.

5.4 Workflow recipes: AI-assisted workflows

Recipe: brainstorming with AI chat

1. Open AI Chat from the sidebar.
2. Describe your problem: "I need ideas for organizing a product launch."
3. The AI generates structured suggestions.
4. Copy useful ideas into a new document page.
5. Expand each idea using AI > Continue Writing.

Recipe: summarizing research

1. Paste your research notes (articles, findings, data) into a document.
2. Select all the content.
3. Use AI > Summarize to get a concise overview.
4. Create a new heading "Key Takeaways" and paste the summary.
5. Use AI > Make Shorter on individual sections that are still too verbose.

Recipe: multilingual content

1. Write your content in your primary language.
2. Select the text you want to translate.
3. Use AI > Translate and choose the target language.
4. Review and adjust the translation. AI translations are a starting point — always review for nuance and context.

Recipe: polishing a draft

1. Write a rough first draft without worrying about grammar or style.
2. Select the entire document content.
3. Use AI > Fix Spelling & Grammar for corrections.
4. Select individual paragraphs and use AI > Improve Writing for tone and clarity.
5. Use AI > Make Longer on sections that need more detail.

5.5 Workflow recipes: theming and customization

Recipe: creating a custom theme

1. Open Settings > Appearance.
2. Choose a base theme (Light or Dark).
3. Customize colors, fonts, and spacing.
4. Export your theme as JSON for backup before updates (themes may be lost on update — issue #8663).

Recipe: optimizing for reading

1. Increase kDocumentAppearanceFontSize for comfortable reading.
2. Set kDocumentAppearanceWidth to a narrower value (e.g., 700px) for optimal line length.
3. Choose a serif font family like Georgia for long-form reading.
4. Enable Dark mode for reduced eye strain in low-light environments.

Recipe: optimizing for data-heavy work

1. Enable Compact Mode on database views for denser row spacing.
2. Set textScaleFactor to 0.8 for more content per screen.
3. Use a monospace font family for databases with code or IDs.
4. Maximize the window and use full-width page layout.

5.6 Workflow recipes: publishing and sharing

Recipe: publishing a team wiki

1. Organize your wiki with a clear hierarchy: Index page with subpages for each topic.
2. Open the Index page and click Share > Publish.
3. Share the generated URL with your team or stakeholders.
4. Updates to published pages are reflected automatically.

Recipe: sharing a project status board

1. Create a database with your project status.
2. Add a Board view showing tasks grouped by status.
3. Publish the Board view.
4. Share the URL in Slack, email, or your project management channel.
5. Stakeholders can view the live board without needing AppFlowy accounts.

5.7 Workflow recipes: import and migration

Recipe: migrating from Notion

1. Export your Notion workspace as Markdown files (Notion > Settings > Export).
2. In AppFlowy, use the import function to bring in Markdown files.
3. Review imported pages for formatting consistency.
4. Reorganize pages into AppFlowy Spaces as needed.

Recipe: importing Markdown documentation

1. Prepare your Markdown files in a folder.
2. Import each file into AppFlowy as a new document page.
3. AppFlowy parses Markdown headings, lists, code blocks, and tables.
4. Adjust any formatting that did not convert cleanly.

6. Troubleshooting

General approach

When encountering issues with AppFlowy:

1. Check your version: ensure you are running the latest release (0.11.4 or newer).
2. Check connectivity: many issues relate to cloud sync. Verify your internet connection.
3. Check logs: AppFlowy writes logs to the data directory. Look for error messages.
4. Restart the application: resolves most transient issues.
5. Clear cache: if the app is sluggish or behaving unexpectedly, clearing the local cache can help (Settings > Files).

Error: error while loading shared libraries: libvdpau.so.1

Cause: The VDPAU (Video Decode and Presentation API for Unix) shared library is not installed on the system. This is a video hardware acceleration library that AppFlowy's underlying framework depends on.

Solution:

# Ubuntu / Debian
sudo apt install libvdpau1

# Fedora
sudo dnf install libvdpau

# Arch Linux
sudo pacman -S libvdpau

Prevention: Install the VDPAU library before launching AppFlowy on a new Linux system. Some minimal server distributions and Docker containers do not include it by default.

(GitHub issue #8655)

Error: App crash on fresh install (Windows 10)

Cause: Compatibility issue with Windows 10 in version 0.11.4. The crash occurs during initial setup before the main window renders.

Solution:

1. Right-click AppFlowy.exe and select Run as Administrator.
2. If the crash persists, try compatibility mode: right-click > Properties > Compatibility > Run in compatibility mode for Windows 8.
3. Check that your Windows 10 installation is fully updated.
4. Try the portable .zip version instead of the installer.

Prevention: This issue is specific to certain Windows 10 configurations. Updating to the latest Windows 10 patch level typically resolves it.

(GitHub issue #8577)

Error: Settings page shows error code without internet connection

Cause: The Settings page attempts to load cloud-related configurations and displays a raw error code when the network request fails instead of a graceful offline message.

Solution:

1. Connect to the internet and reload the Settings page.
2. If you are intentionally offline, ignore the error — local settings still function correctly.
3. Switch to Guest mode if you do not need cloud features while offline.

Prevention: This is a known UI issue. Settings that do not require cloud connectivity (appearance, data path, etc.) work regardless of connection status.

(GitHub issue #8668)

Error: Custom themes lost after app update

Cause: Custom theme data is stored in a location that gets overwritten during the update process.

Solution:

1. Re-import your custom theme JSON file after the update.
2. If you did not back up the theme, recreate it in Settings > Appearance.

Prevention: Before updating AppFlowy, export your custom theme configuration. Store the JSON file outside the AppFlowy data directory.

(GitHub issue #8663)

Error: Data loss when restarting cloud services in offline mode

Cause: Switching cloud providers or restarting cloud sync while the app is offline can cause the local state to become inconsistent with the expected cloud state, leading to data loss during the next sync.

Solution:

1. If data has been lost, check if previous versions exist in the cloud (if you were previously synced).
2. Check the local data directory for backup files.
3. Contact AppFlowy support with your data directory for potential recovery.

Prevention: Never modify cloud settings while offline. Ensure a stable internet connection before changing cloud configuration. Always back up your data directory before switching cloud providers.

(GitHub issue #8635)

Error: AppFlowy Cloud login failed

Cause: Authentication issues with AppFlowy Cloud can stem from network problems, expired tokens, or server-side issues.

Solution:

1. Verify your internet connection.
2. Try logging out and logging back in.
3. Clear app data and re-authenticate.
4. Check status.appflowy.io for service outages.
5. If using a self-hosted instance, verify the cloud URL configuration.

Prevention: Keep AppFlowy updated to ensure token refresh mechanisms are current.

(GitHub issue #8675)

Error: Cannot delete or open grid views in new tab

Cause: A bug in grid view management where certain operations fail silently or produce errors.

Solution:

1. Try closing and reopening the database page.
2. If a grid view cannot be deleted, create a new view with the desired configuration and manually migrate data.
3. Restart AppFlowy.

Prevention: This is a known bug being tracked. Keep AppFlowy updated for fixes.

(GitHub issue #8673)

Error: Duplicating linked view copies same link instead of creating new view

Cause: When duplicating a page that contains a linked database view, the duplicate references the same view instead of creating an independent copy.

Solution:

1. Instead of duplicating, create a new page manually.
2. Add a new view of the same database with its own filters, sorts, and field visibility.
3. This gives you an independent view that does not share settings with the original.

Prevention: Avoid using the duplicate function for pages with linked database views until this behavior is fixed.

(GitHub issue #8636)

Error: Unable to open from Snap Store (Linux)

Cause: The Snap package may have confinement issues or missing dependencies on certain Linux distributions.

Solution:

1. Try running from the terminal: snap run appflowy and check for error messages.
2. Ensure your snapd is updated: sudo snap refresh.
3. If the Snap version continues to fail, use the AppImage or install script instead.

# Remove snap version
sudo snap remove appflowy

# Use AppImage instead
chmod +x AppFlowy-*.AppImage
./AppFlowy-*.AppImage

Prevention: The AppImage and install script methods are generally more reliable on Linux. Use Snap only if your organization requires it.

(GitHub issue #8659)

Error: Document blocks not rendering after paste

Cause: Complex clipboard content (from web pages, Word documents, or other rich text sources) may not parse correctly into AppFlowy's block format.

Solution:

1. Try Paste as Plain Text (Ctrl/Cmd + Shift + V).
2. If specific blocks are corrupted, delete them and re-type the content.
3. For large pastes from external sources, paste into a scratch document first, verify formatting, then copy within AppFlowy to the final location.

Prevention: When pasting from external sources, use plain text paste as the default. Format within AppFlowy using Markdown shortcuts.

Error: Sync conflict after extended offline editing

Cause: Editing the same document on multiple devices while all are offline can create complex merge scenarios when they reconnect.

Solution:

1. Wait for sync to complete on all devices (watch the sync indicator).
2. Review the document for any merged content that needs manual cleanup.
3. AppFlowy's CRDT engine handles most conflicts automatically, but paragraph-level conflicts may result in duplicated content.

Prevention: When possible, work on different pages across devices while offline. The CRDT engine handles concurrent edits well, but working on the same paragraph from multiple devices offline increases the chance of visible merge artifacts.

Error: Images not loading in published pages

Cause: Images uploaded locally are not accessible from the public URL. Only cloud-uploaded images are available in published pages.

Solution:

1. Re-upload images through AppFlowy while connected to AppFlowy Cloud.
2. Alternatively, use external image URLs (paste a link to a publicly hosted image).
3. Re-publish the page after fixing the images.

Prevention: When creating content intended for publishing, ensure you are connected to AppFlowy Cloud so uploads go to cloud storage.

Error: Database filters not persisting

Cause: Filters may not save correctly if the view configuration is corrupted or if the app closes before the filter state is flushed.

Solution:

1. Remove all filters and re-add them one at a time.
2. Switch to another view and back.
3. Restart AppFlowy.

Prevention: After adding or modifying filters, switch to another page and back to verify they persisted.

Error: App slow or unresponsive with large databases

Cause: Databases with hundreds of rows or many views can cause performance degradation, especially on lower-end devices.

Solution:

1. Enable Compact Mode for dense views.
2. Use filters to limit the visible row count.
3. Split very large databases into multiple smaller ones connected via Relation fields.
4. Close unused views/tabs.

Prevention: Keep individual databases under 500 rows for optimal performance. Use filtered views instead of scrolling through all rows.

Error: Cannot sign in after changing cloud URL

Cause: Switching the cloud URL (kAppflowyCloudBaseURL) while signed in can leave the app in an inconsistent authentication state.

Solution:

1. Sign out completely.
2. Close and reopen AppFlowy.
3. Set the new cloud URL in Settings.
4. Sign in again with your credentials for the new cloud instance.

Prevention: Always sign out before changing cloud configuration.

Error: Emoji picker not loading

Cause: The emoji data file may not have loaded correctly, or the UI component may be stuck.

Solution:

1. Try using the slash command /emoji instead of the toolbar emoji button.
2. Restart AppFlowy.
3. If the issue persists, clear the app cache.

Prevention: This is typically a transient UI issue resolved by restart.

Error: Page export produces empty file

Cause: Export may fail silently if the page content uses block types that the export format does not support.

Solution:

1. Try exporting as Markdown instead of JSON, or vice versa.
2. For databases, use CSV export specifically.
3. Copy content manually as a fallback: select all (Ctrl/Cmd + A), copy, paste into a text editor.

Prevention: Test exports on a small page before exporting large documents to verify the format handles your content types.

Error: Search returns no results for known content

Cause: The Tantivy search index may not have been updated after recent edits, or the index may be corrupted.

Solution:

1. Wait a few seconds after editing before searching (the index updates asynchronously).
2. Restart AppFlowy to trigger a re-index.
3. If the issue persists, deleting the search index files from the data directory forces a full re-index on next launch.

Prevention: The search index is maintained automatically. Occasional restarts help ensure index consistency.

Error: File upload fails

Cause: File uploads may fail due to network issues, file size limits, or cloud storage quota.

Solution:

1. Check your internet connection (uploads go to AppFlowy Cloud).
2. Verify the file size is within limits (check AppFlowy Cloud documentation for current limits).
3. Try a smaller file to confirm uploads work.
4. Check your cloud storage quota in Settings.

Prevention: Compress large files before uploading. Use links to external storage for very large files.

Error: Keyboard shortcuts not working

Cause: Shortcut conflicts with the operating system or other applications, or the editor not having focus.

Solution:

1. Click inside the document editor to ensure it has focus.
2. Check for OS-level shortcut conflicts (e.g., macOS Spotlight uses Cmd + Space, which may conflict).
3. Restart AppFlowy.

Prevention: Close or reconfigure other applications that may intercept the same keyboard shortcuts.

Error: Real-time collaboration cursors not visible

Cause: Collaboration cursor display requires an active WebSocket connection to AppFlowy Cloud. Intermittent connectivity can cause cursors to disappear.

Solution:

1. Check your internet connection.
2. Have collaborators refresh their AppFlowy instances.
3. Close and reopen the shared document.

Prevention: A stable internet connection is essential for real-time collaboration features.

Error: Date fields showing incorrect timezone

Cause: Date fields use the system timezone. If your device timezone is misconfigured, dates may appear incorrect.

Solution:

1. Verify your system timezone settings.
2. Restart AppFlowy after correcting the timezone.

Prevention: Ensure your operating system timezone is set correctly, especially on servers or VMs.

Error: Kanban board columns out of order

Cause: The column order in a Kanban board reflects the option order of the grouping field. If options are reordered in the field configuration, the board may not immediately reflect the change.

Solution:

1. Open the grouping field's configuration (click the field header > Edit field).
2. Drag options into the desired order.
3. Switch away from the Board view and back.

Prevention: Set up Select field options in the desired order before creating the Board view.

Error: LaTeX math equations not rendering

Cause: Invalid LaTeX syntax or unsupported commands.

Solution:

1. Verify your LaTeX syntax is valid.
2. Simplify the expression and add complexity incrementally to identify the failing element.
3. AppFlowy supports standard LaTeX math — advanced packages may not be available.

Prevention: Test complex equations in an online LaTeX editor first, then paste the working syntax into AppFlowy.

Error: Import fails with "unsupported format"

Cause: The file format is not recognized or the file is corrupted.

Solution:

1. Ensure the file is valid Markdown (.md).
2. Open the file in a text editor to verify it is not empty or corrupted.
3. Try importing a simpler file to isolate the issue.

Prevention: Use standard Markdown syntax. Remove any proprietary formatting before import.

Error: REST API — SingleSelect fields remain empty on PUT /row

Cause: This is a known issue in the REST API layer where SingleSelect field values are not properly written during row updates.

Solution:

1. As a workaround, set SingleSelect values through the AppFlowy GUI.
2. If automating, try creating the row with the SingleSelect value set during creation rather than updating it afterward.

Prevention: This is a known bug being tracked. Monitor the issue for patches.

(GitHub issue #8665)

7. FAQ

Q: Is AppFlowy free to use? Yes. AppFlowy is open-source software released under the AGPL-3.0 license. The desktop and mobile apps are free. AppFlowy Cloud offers a free tier for individual use, with paid plans for teams and advanced features.

Q: Where is my data stored? By default, AppFlowy stores all data locally on your device in the application data directory (pathLocation). When connected to AppFlowy Cloud, data syncs to cloud servers while maintaining a local copy. You remain in control of your data at all times.

Q: Can I use AppFlowy completely offline? Yes. Sign in as Guest and all data stays local. You do not need internet access for any core functionality. AI features, cloud sync, and publishing require connectivity.

Q: How do I back up my data? Copy your entire AppFlowy data directory to a backup location. The data directory contains all your documents, databases, and settings. On macOS: ~/Library/Application Support/AppFlowy/. On Windows: %APPDATA%\AppFlowy\. On Linux: ~/.appflowy/.

Q: Can I sync data between devices without AppFlowy Cloud? Not directly. AppFlowy's sync mechanism relies on AppFlowy Cloud (or a self-hosted instance). Without cloud sync, you would need to manually transfer the data directory, which is not recommended as it can cause conflicts.

Q: How do I self-host AppFlowy Cloud? AppFlowy Cloud is available as an open-source project. See the AppFlowy Cloud repository for deployment instructions. Once your instance is running, configure the kAppflowyCloudBaseURL setting in AppFlowy to point to your server. See the Admin Guide for full self-hosting details.

Q: What programming languages is AppFlowy built with? The frontend is built with Flutter (Dart) for cross-platform UI. The backend is built with Rust (rust-lib) for performance and safety. The cloud infrastructure uses a combination of Rust and Go.

Q: Can multiple people edit the same document at the same time? Yes, when using AppFlowy Cloud. AppFlowy uses CRDT (Conflict-free Replicated Data Types) for real-time collaboration, allowing multiple users to edit simultaneously without conflicts.

Q: Does AppFlowy support Markdown? Yes. AppFlowy's editor supports Markdown shortcuts for formatting as you type. You can also import and export Markdown files. The editor converts Markdown syntax into rich blocks in real-time.

Q: How do I create a table of contents? Type /outline in a document to insert an auto-generated table of contents block. It lists all headings and updates automatically.

Q: Can I embed a database inside a document? Yes. Use /grid, /board, or /calendar slash commands to insert an inline database view within any document.

Q: How do I change the language of the interface? Go to Settings > Language and select your preferred language. AppFlowy supports numerous languages through community translations.

Q: Is there a mobile app? Yes. AppFlowy is available on iOS (App Store) and Android (Google Play). The mobile apps sync with your cloud account and support most features available on desktop.

Q: How do I delete my account? For AppFlowy Cloud accounts, go to Settings > Account and look for the delete account option. This removes your cloud data. Local data on your devices remains until you manually delete it.

Q: Can I use AppFlowy for team collaboration? Yes. Create a workspace, invite team members via email, and share Spaces or individual pages. Team members can edit in real-time, leave comments, and manage permissions.

Q: What file types can I upload? AppFlowy supports uploading any file type. Files are stored locally or in AppFlowy Cloud. There may be size limits depending on your cloud plan.

Q: How do I create a template? AppFlowy does not have a built-in template marketplace (as of 0.11.4), but you can create your own template pages and duplicate them when needed. Structure a page with your desired layout, then right-click > Duplicate to create a copy.

Q: Can I link databases together? Yes. Use the Relation field type to create links between rows in different databases. This enables parent-child relationships, many-to-many associations, and cross-referencing.

Q: How do I use AppFlowy with dark mode? Go to Settings > Appearance and select the Dark theme. AppFlowy remembers your theme preference across sessions.

Q: What is the difference between a Space and a Page? A Space is an organizational container (like a folder) that holds multiple pages. A Page is a single document, database, or board. Spaces help you group related pages by project, team, or topic.

Q: Can I publish a database view? Yes. Open the database view you want to share, click Share > Publish, and share the generated URL. Viewers can see the data but cannot edit it.

Q: How do I create a checklist inside a database row? Add a Checklist field type to your database. In each row, you can add multiple sub-items. The cell displays a progress bar showing completion status.

Q: Does AppFlowy support RTL (right-to-left) languages? Yes. Set the kDocumentAppearanceDefaultTextDirection to RTL in Settings > Appearance. The editor layout adjusts for Arabic, Hebrew, and other RTL scripts.

Q: How do I recover a deleted page? Open Trash in the sidebar. Find the deleted page and click the restore icon. The page returns to its original location. Pages in Trash are retained until you permanently delete them or empty the Trash.

Q: Can I use keyboard shortcuts to format text? Yes. See the keyboard shortcuts reference in Section 4.2. Common shortcuts: Ctrl/Cmd + B for bold, Ctrl/Cmd + I for italic, Ctrl/Cmd + K for links.

Q: What happens if I lose internet while editing a cloud-synced document? Your edits are saved locally and queued for sync. When connectivity is restored, changes are automatically merged with the cloud version using CRDT conflict resolution.

Q: Can I export all my data at once? There is no one-click "export everything" feature in version 0.11.4. You can export individual pages (Markdown, JSON) and databases (CSV). For a full backup, copy the data directory.

Q: How does the AI feature work? Is my data sent to external servers? When using AppFlowy Cloud AI, your selected text is sent to the AI model for processing. When using Ollama (local AI), all processing happens on your device with no external data transmission.

Q: What is the maximum number of pages I can create? There is no hard limit on the number of pages in AppFlowy. Performance depends on your device's resources and, if using cloud sync, your plan's storage quota.