Overview

FlowState-CLI started as a personal itch I needed to scratch. As someone who lives in the terminal, I was tired of switching to web apps or GUI tools just to track tasks or start a Pomodoro timer. I wanted something lightweight, fast, and that worked the way I work - entirely from the command line.

What started as a simple script grew into a full productivity tool that I now use internally for all my task management and focus sessions.

The Problem I Was Solving

Existing productivity tools had several issues for my workflow:

  • Context switching: Having to leave the terminal broke my flow
  • Heavyweight solutions: Most tools were overkill for simple task tracking
  • Cloud dependency: I wanted something that worked offline but could sync when needed
  • Poor CLI experience: Web-first tools with afterthought terminal interfaces

I needed something that felt native to the terminal while being powerful enough for real productivity work.

How I Built It

Core Architecture

  • Language: Python with Typer for the CLI interface and Rich for beautiful terminal output
  • Local Storage: SQLite for offline-first task management
  • Backend Services: FastAPI + PostgreSQL for optional cloud sync
  • Authentication: JWT-based auth for sync features
  • Deployment: Packaged and published to PyPI for easy installation

Key Features I Implemented

Task Management

# Quick task creation and management
flow task add "Implement user authentication"
flow task list --status active
flow task complete 123

Pomodoro Timers

# Start focused work sessions
flow pomodoro start --task 123 --duration 25
flow break start --duration 5

Technical Deep Dive

The beauty of FlowState-CLI is in its simplicity. Here’s how the key components work:

Local-First Architecture

# SQLite for offline functionality
class TaskManager:
    def __init__(self, db_path="~/.flowstate/tasks.db"):
        self.db = sqlite3.connect(db_path)
        self.setup_tables()
    
    def add_task(self, description, project=None):
        # Store locally first, sync later
        task_id = self.db.execute(
            "INSERT INTO tasks (description, project, created_at) VALUES (?, ?, ?)",
            (description, project, datetime.now())
        ).lastrowid
        
        # Queue for sync if online
        if self.sync_enabled:
            self.queue_for_sync(task_id)
        
        return task_id

Clean CLI Interface Using Typer and Rich, the CLI feels responsive and looks great:

@app.command()
def add(description: str, project: Optional[str] = None):
    """Add a new task"""
    task_id = task_manager.add_task(description, project)
    console.print(f"✅ Added task {task_id}: {description}", style="green")

@app.command()
def pomodoro(duration: int = 25):
    """Start a Pomodoro session"""
    with Progress() as progress:
        timer_task = progress.add_task(f"Focus time: {duration}m", total=duration*60)
        # Timer logic with live updates

Optional Cloud Sync The sync functionality is built as an optional layer:

class SyncManager:
    def __init__(self, api_base_url, jwt_token):
        self.api_client = httpx.AsyncClient()
        self.token = jwt_token
    
    async def sync_tasks(self):
        # Push local changes to server
        local_changes = self.get_local_changes()
        await self.api_client.post("/sync", json=local_changes)
        
        # Pull remote changes
        remote_changes = await self.api_client.get("/sync/latest")
        self.apply_remote_changes(remote_changes)

Real-World Usage

I’ve been using FlowState-CLI daily for my own work, and it’s become an essential part of my development workflow:

  • Task Management: Quick capture of ideas without leaving the terminal
  • Focus Sessions: 25-minute Pomodoros while coding or studying
  • Project Tracking: Organizing work across different repos and clients
  • Time Awareness: Understanding where my productive hours actually go

Example Workflow

# Start the day by reviewing tasks
$ flow task list

# Add a new feature to work on
$ flow task add "Implement user authentication" --project web-app

# Start a focused work session
$ flow pomodoro start --task 123 --duration 25

# Take a break when the timer ends
$ flow break start --duration 5

# Mark task as complete
$ flow task complete 123

What I Learned

Building FlowState-CLI taught me a lot about:

  • CLI UX Design: Making terminal interfaces that feel intuitive and responsive
  • Local-First Software: Designing apps that work offline but sync when possible
  • Python Packaging: Getting a CLI tool properly packaged and distributed to PyPI
  • Background Processes: Handling timers and notifications without blocking the terminal

Future Plans

The tool is stable and functional for daily use, but I have some ideas for enhancements:

  • Better Analytics: More detailed insights into productivity patterns
  • Plugin System: Allow custom commands and integrations
  • Team Features: Shared projects and team productivity tracking
  • Integration APIs: Connect with other tools like Git, Slack, etc.

Try It Yourself

FlowState-CLI is available on PyPI and ready to use:

pip install flowstate-cli
flow --help

The tool is designed to be immediately useful without configuration, but flexible enough to adapt to different workflows. Give it a try if you’re looking for a terminal-native productivity solution that respects your privacy and keeps you in your flow state.

Want to contribute or have ideas for features? The project is open to collaboration - reach out and let’s build better productivity tools together.

Example Usage

Task Management

flowstate add "Write project documentation"
flowstate list
flowstate start 1
flowstate done 1
flowstate rm 1

Pomodoro & Focus Timer

flowstate pom start
flowstate pom break short
flowstate pom stop
flowstate pom status

Distraction Blocking (Flow State Mode)

flowstate mode on   # Block distracting sites
flowstate mode off  # Unblock

Productivity Stats

flowstate stats

Configuration

flowstate config show
flowstate config set pomo_duration 30
flowstate config set notifications true

Project Setup

Dependencies

pip install flowstate-cli

Configuration

  • All settings are managed via a simple config file or CLI flags.
  • Session logs and task data are stored locally for privacy and review.

Impact

flowstate-cli is helping developers and creators:

  • Reduce distractions and context switching
  • Build sustainable deep work habits
  • Track and reflect on their productivity
  • Automate and script their focus routines

Conclusion

flowstate-cli is more than just a timer, it’s a complete productivity platform for the terminal. By combining simplicity, privacy, and extensibility, it empowers anyone to reclaim their most valuable resource: attention.

For more projects, check out my portfolio!