Skip to main content

FlowState CLI - Lightweight Hybrid Productivity Tool

A minimal command-line interface for task management and Pomodoro timers that works both online and offline.

✨ Features

  • 🔄 Hybrid Mode: Seamlessly switch between cloud sync and offline-first operation
  • 📝 Task Management: Create, track, and complete tasks with local SQLite storage
  • 🍅 Pomodoro Timer: Built-in timer with background daemon support
  • ⚡ Offline-First: Full functionality without internet connection
  • 🔒 Local Authentication: No cloud dependency for basic features
  • 📊 Simple Sync: Manual sync when you want it
  • 💾 Lightweight: Minimal dependencies, SQLite database

🚀 Quick Installation

# Clone and install
git clone <repository-url>
cd flowstatecli
chmod +x install.sh
./install.sh

Or install manually:

pip install -r requirements.txt
pip install -e .

🎯 Operating Modes

FlowState CLI supports three lightweight operating modes:

1. Hybrid Mode (Default)

  • Prefers cloud sync when online
  • Falls back to local storage when offline
  • Best of both worlds

2. Local Mode

  • Completely offline operation
  • Local SQLite database
  • Zero external dependencies

3. Cloud Mode

  • Uses cloud API when available
  • Requires internet connection
  • Traditional online experience

⚙️ Configuration

Quick Setup

# Set operating mode
flowstate mode set hybrid  # or 'local' or 'cloud'

# Check current status
flowstate mode status

# For local/hybrid modes, create local account (username-based)
flowstate auth local-register

# For cloud mode, use magic link (email-based)
flowstate auth login your-email@example.com

Mode Management

# Switch modes anytime
flowstate mode set local     # Go offline-only
flowstate mode set cloud     # Go cloud-only  
flowstate mode set hybrid    # Best of both

# Manual sync (hybrid/cloud modes)
flowstate sync now

# Check connectivity and auth status
flowstate mode status

Usage

Task Management

# Add a new task
flowstate add "Fix the authentication bug"

# List all tasks
flowstate list

# Start working on a task
flowstate start 1

# Complete a task
flowstate done 1

# Delete a task
flowstate rm 1

Pomodoro Timer

# Start a 25-minute focus session
flowstate pom start

# Take a short break (5 minutes)
flowstate pom break short

# Take a long break (15 minutes)
flowstate pom break long

# Stop current timer
flowstate pom stop

# Show current timer status
flowstate pom status

Flow State Mode

# Block distracting websites
flowstate mode on

# Unblock websites
flowstate mode off

# Show flow state mode status
flowstate mode status

Productivity Stats

# Show your productivity statistics
flowstate stats

Configuration

# Show current settings
flowstate config show

# Update Pomodoro duration to 30 minutes
flowstate config set pomo_duration 30

# Update short break duration to 10 minutes
flowstate config set short_break 10

# Update long break duration to 20 minutes
flowstate config set long_break 20

# Enable notifications
flowstate config set notifications true

# Disable notifications
flowstate config set notifications false

🔄 Data Synchronization

Manual Sync

# Force sync now (hybrid/cloud modes)
flowstate sync now

# Check sync status
flowstate mode status

Conflict Resolution

  • Simple approach: Local changes take priority
  • Manual sync: Sync only when you want it
  • Lightweight: No complex background processes

💾 Local Storage

All data is stored locally in ~/.flowstate/:

  • config.json - User preferences and mode settings
  • local.db - SQLite database with tasks and pomodoros
  • auth.json - Local authentication tokens

📊 Dependencies

Minimal and lightweight:

  • Core: typer, rich, httpx (for cloud features)
  • Database: sqlalchemy (with SQLite)
  • Auth: bcrypt, PyJWT (for local auth)
  • Notifications: plyer (optional system notifications)

Total install size: ~15MB

📊 Authentication Options

Local Authentication

# Register new local account (username-based)
flowstate auth local-register

# Login to existing local account  
flowstate auth local-login

# Logout from current session
flowstate auth logout

Cloud Authentication

# Magic link authentication (email-based)
flowstate auth login your-email@example.com
flowstate auth token <your-cli-token>

# Check auth status
flowstate mode status

Metadata

Release files for flowstate-cli 1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flowstate-cli 1.3
File Size Uploaded Provenance Actions
flowstate_cli-1.3.tar.gz 23.0 kB Without provenance Details for flowstate_cli-1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flowstate-cli 1.3
File Interpreter ABI Platform Actions
flowstate_cli-1.3-py3-none-any.whl Python 3 none any Details for flowstate_cli-1.3-py3-none-any.whl

Total release size: 48.7 kB

Release files / flowstate_cli-1.3.tar.gz

Download URL flowstate_cli-1.3.tar.gz
Size 23.0 kB
Tags Source
SHA-256 checksum
How to use checksums
fa3c60516855b6c86d31ac0acaae9685fb552299a90670959989a5c2a3a71e77
BLAKE2b-256 checksum
How to use checksums
84756b00b93e2e3ac45ecb45e1686bf29de2fa5d60d81f4c9e4f1e1dbb2f589e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.3

Release files / flowstate_cli-1.3-py3-none-any.whl

Download URL flowstate_cli-1.3-py3-none-any.whl
Size 25.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a94040a31bcb0e6736473a18967426a56529608a1e312898bdb15a548a494be8
BLAKE2b-256 checksum
How to use checksums
5f1f07bc6fe6a60817588bf8be79e511d40e51d9d8f23de7a9876cc6dd4166fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.3

Security for flowstate-cli 1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page