flow-cli

ZSH workflow tools designed for ADHD brains. Start working in 10 seconds. Stay motivated with visible wins.

⚡ 10-Second Start

# 1. Install
brew install data-wise/tap/flow-cli   # macOS (recommended)
# or: antidote install data-wise/flow-cli
# or: zinit light data-wise/flow-cli

# 2. Work
work my-project    # Start session
win "Fixed bug"    # Log win → get dopamine
finish             # Done for now

That's it. Everything else is optional.

!!! info "Zero Dependencies" flow-cli is a standalone ZSH plugin with no dependencies on Oh-My-Zsh, antidote, or any other framework. Choose any installation method that works for you.

What's New

v7.4.0: 31 Email Commands

• Organize: em star, em thread, em snooze, em digest — manage your inbox without leaving the terminal
• Manage: em delete, em move, em restore, em flag, em todo, em event — full email lifecycle with --pick multi-select
• AI: Switch backends with em ai gemini, capture tasks with em catch 42
• 10 Tutorials — step-by-step guides for every em subcommand

em star 42                   # Star a message
em move 42 Archive           # Move to folder
em todo 42                   # Create reminder from email
em pick                      # Interactive multi-select

Full Changelog | All Releases

$ work my-project
🚀 Starting session: my-project
   📍 ~/projects/my-project

$ win "Fixed the login bug"
🔧 fix: Fixed the login bug
   ✨ Win #1 today!

$ win "Added unit tests"
🧪 test: Added unit tests
   ✨ Win #2 today!

$ yay
╭──────────────────────────────────────╮
│ 🏆 Today's Wins (2)                 │
├──────────────────────────────────────┤
│ 🔧 Fixed the login bug              │
│ 🧪 Added unit tests                 │
╰──────────────────────────────────────╯
   🔥 2-day streak!

$ finish
✅ Session complete (47 min, 2 wins)

🎯 Why This Exists

🚀 Core Commands

Start & Stop

work myproject     # Start working (creates session)
finish "done X"    # End session (optional commit)
hop other          # Quick switch (tmux)

Stay Motivated

win "Fixed the bug"     # Log accomplishment → 🔧 fix
win "Deployed v2"       # Log accomplishment → 🚀 ship
yay                     # See your wins
flow goal set 3         # Daily target

Stay Oriented

dash           # What's happening?
why            # Where was I?
pick           # Choose a project

🧠 ADHD-Friendly Features

🏆 Dopamine Hits

Every win gives you a category and emoji:

• 💻 code - "Implemented feature"
• 🔧 fix - "Fixed that bug"
• 🚀 ship - "Deployed to prod"
• 📝 docs - "Updated README"
• 🧪 test - "Added tests"

🔥 Streak Tracking

Day 1: work → 🌱 1 day
Day 3: work → 🔥 3 days - On a roll!
Day 7: work → 🔥🔥 Strong week!

📊 Dashboard

dash              # Quick overview
dash -i           # Interactive picker
dash --watch      # Live updates

☁️ Multi-Device Sync (v4.7.0)

Sync your wins and goals across devices via iCloud:

flow sync remote init    # Set up once
flow sync                # Auto-sync daily

Works offline, syncs when connected. Zero config after setup.

⚡ Performance Optimization (v5.3.0)

Sub-10ms project picker with intelligent caching:

pick              # < 10ms (cached)
flow cache status # Check cache age
flow cache refresh # Force rebuild

40x faster than v5.2.0 for large project sets (100+ repos). Transparent 5-minute cache with automatic refresh.

🔌 Smart Dispatchers

Context-aware commands that adapt to your project:

Each dispatcher has built-in help: cc help, dots help, r help, em help, at help, etc.

✨ New in v7.6.0: em --prompt AI-guided composition, --backend provider override, em forward, help guards on all 34 em subcommands ✨ v7.5.0: em v2.0 safety gate, ICS calendar, IMAP watch, folder CRUD ✨ v7.4.2: Atlas bridge (at) — project intelligence, context parking, quick capture ✨ v7.4.0: 38 email commands — read, reply, forward, AI compose, organize, manage ✨ v7.1.0: Dispatcher split — dot → dots (dotfiles) + sec (secrets) + tok (tokens) ✨ 15 dispatchers + Atlas bridge with unified grammar, built-in help, and fzf integration

🎓 Teaching Workflow

Deployment-focused workflow for course websites. Solve the 5-15 minute deployment pain point.

v7.6.0: Scholar Config Sync — teach config check/diff/show/scaffold, teach solution, teach sync, teach validate-r.

# Initialize teaching workflow (with semester scheduling)
cd ~/teaching/my-course
teach init "STAT 545"
# Prompts for: semester dates, break weeks, auto-calculates end date

# Start session (shows semester context)
work stat-545
📚 STAT 545 - Design of Experiments
  Branch: draft
  Semester: Spring 2026
  Current Week: Week 8

  Recent Changes:
    Add week 8 lecture notes
    Update assignment rubric

# Deploy (typo to live in < 2 min)
./scripts/quick-deploy.sh

Key Features:

• ✅ Fast Deployment - < 2 minute typo-to-live workflow
• ✅ Branch Safety - Warns when editing production (students see this!)
• ✅ Semester Context - Shows current week, detects breaks, displays recent commits
• ✅ Week Calculation - Auto-calculates week number from semester start date
• ✅ Automation Scripts - One-command deployment and archival
• ✅ Semester Management - Easy semester transitions with archival tags
• ✅ Config Validation (v5.9.0) - Schema-based validation with hash caching
• ✅ Scholar Integration (v5.8.0+) - AI-powered exam/quiz/slides generation

Scholar AI Commands (v5.8.0+):

teach exam "Hypothesis Testing"  # Generate exam via Scholar plugin
teach quiz "Chapter Review"      # Generate quiz
teach slides "Regression"        # Generate lecture slides
teach --dry-run exam "Topic"     # Preview without writing files
teach map                        # Show full ecosystem overview

Learn More:

• Complete Guide
• Quick Reference
• Demo Walkthrough

📚 Quarto Workflow Phase 1 (v4.6.0+)

Professional teaching workflow with automated validation, caching, and deployment.

Automated Validation

• Git Hooks: Automatic validation on commit/push
  • 5-layer validation: YAML, syntax, render, empty chunks, images
  • Production branch protection
  • Zero-config installation
• teach validate: Standalone validation with watch mode
  • Four modes: --yaml, --syntax, --render, full
  • Continuous validation with file system monitoring
  • Conflict detection with quarto preview

Cache Management

• teach cache: Interactive Quarto freeze cache management
  • Status, clear, rebuild, analyze, clean operations
  • Storage analysis and diagnostics
  • TUI menu for easy interaction

Health Monitoring

• teach doctor: Comprehensive health checks
  • 6 check categories (dependencies, config, git, scholar, hooks, cache)
  • Interactive fix mode (--fix flag)
  • JSON output for CI/CD integration

Enhanced Deployment

• Index Management: Automatic ADD/UPDATE/REMOVE of links
  • Smart week-based link insertion in index.qmd
  • Source file and cross-reference detection
  • Partial deployment support
  • Preview mode before PR creation

Backup Management

• Retention Policies: Daily/weekly/semester archival rules
  • Archive support for semester-end
  • Storage-efficient incremental backups
  • Safe deletion with confirmation

Status Dashboard

• 6-Section Overview: Project, Git, Deployment, Backup, Scholar, Hooks
  • Color-coded health indicators
  • Comprehensive project information
  • All information in one command

Example Workflow:

# Check project health
teach doctor
teach doctor --fix  # Interactive dependency installation

# Validate .qmd files
teach validate lectures/week-01.qmd
teach validate --watch  # Continuous validation

# Manage Quarto freeze cache
teach cache              # Interactive TUI menu
teach cache status       # View cache size
teach cache rebuild      # Clear and regenerate

# Install git hooks (automatic validation)
teach hooks install
teach hooks status

# Deploy with index management
teach deploy --preview   # Preview changes first
teach deploy             # Create PR with index updates

# Check comprehensive status
teach status             # 6-section dashboard

Documentation:

• Quarto Workflow Guide
• Teach Dispatcher Reference

📦 Installation

Homebrew (Recommended for macOS)

# Tap the repository
brew tap data-wise/tap

# Install flow-cli
brew install flow-cli

That's it! Homebrew handles everything. No plugin manager needed.

Alternative: Quick Install Script

curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/install.sh | bash

Auto-detects your plugin manager and installs accordingly.

Install specific version:

FLOW_VERSION=v4.8.0 curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/install.sh | bash

Installation Methods Comparison

echo "Data-Wise/flow-cli" >> ~/.zsh_plugins.txt
antidote update

zinit light Data-Wise/flow-cli

git clone https://github.com/Data-Wise/flow-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/flow-cli
# Then add 'flow-cli' to plugins=(...) in ~/.zshrc

git clone https://github.com/Data-Wise/flow-cli.git ~/.flow-cli
echo 'source ~/.flow-cli/flow.plugin.zsh' >> ~/.zshrc

Verify Installation

flow doctor        # Health check

Uninstall

curl -fsSL https://raw.githubusercontent.com/Data-Wise/flow-cli/main/uninstall.sh | bash

✅ Testing

Interactive dog feeding test (yes, really):

./tests/interactive-dog-feeding.zsh

• 🐕 Feed a virtual dog by confirming commands work
• ⭐ Earn 1-5 stars
• 👀 See expected output before running

⚙️ Configuration

# In .zshrc (before sourcing plugin)
export FLOW_PROJECTS_ROOT="$HOME/projects"  # Where your projects live
export FLOW_QUIET=1                         # Skip welcome message

📚 Documentation

• Quick Start - 5 minutes
• Dopamine Features - Win tracking
• Sync Command - Multi-device sync
• All Commands - Reference

API Reference

348 functions documented across 32 library files (49.4% coverage):

🤝 Philosophy

1. Instant response - Sub-10ms, no waiting
2. Smart defaults - Works without config
3. Visible progress - See your wins
4. Low friction - Start working fast

License: MIT Docs: data-wise.github.io/flow-cli