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 settingslocal.db- SQLite database with tasks and pomodorosauth.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.