Introduction

Welcome to the Flow Book - the official documentation for Flow, a developer-first note-taking tool.

Thoughts captured. Focus unbroken.

What is Flow?

Flow is an outliner-first note-taking application with object-based notes designed for developers. It stays out of your way, letting you capture thoughts without breaking your concentration.

# Capture a thought without leaving your terminal
flow capture "Research CRDT sync options for offline-first #idea"

# Done. Back to work.

Philosophy

Flow is built on principles that put you in control:

1. Local-First - Your data belongs to you, stored on your machine
2. Plain Text - Markdown files you can read in any editor
3. No Lock-In - Your notes are just files, take them anywhere
4. Outliner-First - Organize thoughts hierarchically, add prose when needed
5. Developer-Friendly - Built for terminal workflows and automation
6. Progressive Enhancement - Start simple, add complexity as needed

Components

Flow is modular - use what you need:

Project Status

⚠️ Flow is in early development. The core architecture is being built, and features are being actively developed. This documentation will evolve alongside the project.

Getting Started

Ready to dive in? Head to the Installation guide to get started.

Links

• GitHub Repository
• Issue Tracker
• Discussions

Installation

This guide covers how to install Flow on your system.

Pre-built Binaries

The easiest way to install Flow is to download a pre-built binary from the GitHub Releases page.

Binary Variants

Flow comes in several variants depending on your needs:

Download

1. Go to the Releases page

2. Download the appropriate archive for your platform:

   • Linux: flow-<variant>-linux-x86_64.tar.gz or flow-<variant>-linux-aarch64.tar.gz
   • macOS: flow-<variant>-macos-x86_64.tar.gz (Intel) or flow-<variant>-macos-aarch64.tar.gz (Apple Silicon)
   • Windows: flow-<variant>-windows-x86_64.zip

3. Extract and install:

Linux / macOS

# Extract (example for CLI variant on Linux x86_64)
tar -xzf flow-linux-x86_64.tar.gz

# Move to a directory in your PATH
sudo mv flow /usr/local/bin/

# Verify installation
flow --version

Windows

1. Extract the .zip file
2. Move flow.exe to a directory in your PATH (e.g., C:\Users\<username>\bin)
3. Open a new terminal and verify:

flow --version

Building from Source

Prerequisites

• Rust (stable toolchain, version 1.91.1 or later)
• Git

Clone and Build

# Clone the repository
git clone https://github.com/mrbandler/flow.git
cd flow

# Build the CLI (default)
cargo build --release --package flow

# Or build with specific features
cargo build --release --package flow --features tui      # CLI + TUI
cargo build --release --package flow --features gui      # CLI + GUI
cargo build --release --package flow --features all      # Everything

The binary will be at target/release/flow (or target/release/flow.exe on Windows).

Install via Cargo

# Install the CLI
cargo install --git https://github.com/mrbandler/flow.git flow

# Install with TUI
cargo install --git https://github.com/mrbandler/flow.git flow --features tui

Using Nix

If you use Nix, you can enter a development shell with all dependencies:

# Clone the repository
git clone https://github.com/mrbandler/flow.git
cd flow

# Enter the development shell
nix develop

Verifying Your Installation

After installation, verify Flow is working:

# Check version (shows compiled features)
flow --version
# Output: flow 0.1.0 (tui, gui)  -- features vary by variant

# Show help
flow --help

Next Steps

Now that Flow is installed, head to the Quick Start guide to begin using it!

Quick Start

This guide will help you get started with Flow in just a few minutes.

Your First Capture

The most basic Flow command is capture - it lets you quickly save a thought without interrupting your workflow:

flow capture "Remember to review the API design"

That’s it! Your thought is saved. You can continue with what you were doing.

Adding Context with Tags

Make your notes more organized by adding tags:

flow capture "Implement caching layer #backend #performance"

Tags help you find related notes later.

Linking Ideas

Reference other notes using double brackets:

flow capture "This relates to [[API Design]] discussion"

Flow automatically creates bidirectional links between your notes.

Viewing Your Notes

List your recent captures:

flow list

Search across all your notes:

flow search "API"

Creating a Space

Spaces help you organize different areas of your life or work:

# Initialize a new space in the current directory
flow init

# Or create a named space
flow init --name "work-notes"

Next Steps

• Learn about Core Concepts to understand Flow’s philosophy
• Explore the CLI Reference for all available commands
• Read about Spaces to organize your knowledge

Tip: Add flow capture to a shell alias for even faster capture:

alias fc="flow capture"

Configuration

Core Concepts

This chapter explains the fundamental concepts behind Flow. Understanding these will help you get the most out of the tool.

Outliner-First

Flow is built around the idea that thinking happens in outlines. Instead of starting with a blank page, you start with bullet points that can be nested, rearranged, and expanded.

- Project ideas
  - Flow improvements
    - Add vim keybindings
    - Implement sync server
  - Blog posts to write
    - Why outliners beat documents

Each bullet point is a discrete unit of thought that can:

• Be collapsed or expanded
• Be referenced from elsewhere
• Have properties attached
• Be queried and filtered

Object-Based Notes

Every item in Flow is an object with:

1. Content - The text you write
2. References - Links to other objects ([[like this]])
3. Tags - Classification markers (#tag)
4. Properties - Key-value metadata (status:: active)

This means your notes aren’t just text—they’re queryable data.

Knowledge Graph

All your notes form a graph of interconnected ideas:

• Nodes are your notes/bullets
• Edges are references between them
• Tags group related nodes
• Properties add structured data

You can traverse this graph, find connections, and query it like a database.

Spaces

A space is a collection of notes, typically stored in a single directory. You might have:

• A personal space for life management
• A work space for project notes
• A space per major project

Spaces are independent but can reference each other.

Local-First

Your data lives on your machine in plain Markdown files:

• No cloud dependency
• No vendor lock-in
• Version control friendly
• Readable without Flow

Sync is opt-in and self-hosted.

Continue to the next chapters to learn about each concept in detail.

Spaces

Notes & Outlines

Tags & Properties

Links & References

Views & Queries

CLI Usage

TUI Interface

Desktop Application

Workflows

Quick Capture

Daily Notes

Project Management

CLI Reference

This chapter provides a complete reference for all Flow CLI commands.

Note: Flow is in early development. Commands and options may change.

Global Options

These options can be used with any command:

Commands

flow capture

Quickly capture a thought without leaving your terminal.

flow capture "Your thought here #tag"

Arguments:

Examples:

# Simple capture
flow capture "Remember to update the docs"

# Capture with tags
flow capture "Research CRDT sync options #idea #research"

# Capture to a specific space
flow -s work capture "Meeting notes from standup"

flow search

Search your knowledge base.

flow search <QUERY>

Arguments:

Examples:

# Simple search
flow search "project ideas"

# Search with tags
flow search "#rust #async"

flow list

List notes in the current space.

flow list [OPTIONS]

Options:

flow init

Initialize a new Flow space.

flow init [PATH]

Arguments:

Examples:

# Initialize in current directory
flow init

# Initialize in a specific directory
flow init ~/notes/personal

UI Commands

These commands launch interactive interfaces (requires respective features to be compiled in).

flow tui

Launch the Terminal User Interface.

flow tui

Requires the tui feature.

flow gui

Launch the Desktop GUI application.

flow gui

Requires the gui feature.

flow serve

Start the Flow server for sync and web access.

flow serve [OPTIONS]

Requires the server feature.

Environment Variables

Exit Codes

Configuration File

File Format

Query Language

Contributing

Architecture

Building from Source

Changelog