Pomodoro CLI

A command-line Pomodoro timer for focused work sessions, built with Rust.

Features

• Automatic Phase Transitions: Seamlessly cycles through focus, short break, and long break phases
• Session Management: Pause, resume, skip, and stop sessions with ease
• Customizable Durations: Configure focus time, break intervals, and cycle counts
• Profile Support: Save and reuse different timer configurations
• Statistics Tracking: View daily, weekly, and monthly productivity stats
• Data Export: Export statistics to CSV or JSON formats
• Beautiful CLI Output: Color-coded phases with progress bars
• Tag Support: Organize sessions with tags for better tracking

Installation

# Clone the repository
git clone https://github.com/yourusername/pomodoro-cli.git
cd pomodoro-cli

# Build and install
cargo build --release
cargo install --path .

Usage

Basic Commands

# Start a new Pomodoro session
pomo start "Write documentation"

# Start with tags
pomo start "API development" --tag coding --tag backend

# Check current status
pomo status

# Pause the current session
pomo pause

# Resume a paused session
pomo resume

# Skip to the next phase
pomo skip

# Stop the current session
pomo stop

Custom Durations

# Custom focus and break times
pomo start --focus-min 50 --short-min 10 --long-min 20

# Custom cycle count before long break
pomo start --cycles 3

# Disable automatic transitions
pomo start --no-auto

Profiles

# Save current settings as a profile
pomo profile save deepwork

# Use a saved profile
pomo start --profile deepwork

# List all profiles
pomo profile list

# Show profile details
pomo profile show deepwork

# Delete a profile
pomo profile delete deepwork

Statistics

# View today's statistics
pomo stats --today

# View weekly statistics
pomo stats --week

# View monthly statistics
pomo stats --month

# View statistics for a date range
pomo stats --range 2025-08-01..2025-08-15

# Export statistics to CSV
pomo stats --week --export csv

# Export statistics to JSON
pomo stats --month --export json

# Group statistics by tag or task
pomo stats --week --by tag
pomo stats --week --by task

Configuration

# Initialize configuration file
pomo config init

# Show configuration file path
pomo config path

# Set configuration values
pomo config set focus_min 25
pomo config set short_min 5
pomo config set long_min 15
pomo config set cycles 4
pomo config set auto_next true
pomo config set notify true

Default Settings

• Focus Time: 25 minutes
• Short Break: 5 minutes
• Long Break: 15 minutes
• Cycles before Long Break: 4
• Auto Transition: Enabled

Phase Flow

Focus (25 min) → Short Break (5 min) → Focus → Short Break → Focus → Short Break → Focus → Long Break (15 min)
                                                                                                    ↑
                                            [Repeat after 4 focus sessions]

Data Storage

Pomodoro CLI stores data in platform-specific directories:

• Linux: ~/.config/pomo/ (config) and ~/.local/share/pomo/ (data)
• macOS: ~/Library/Application Support/pomo/ (config and data)
• Windows: %APPDATA%\pomo\ (config and data)

Files

• config.toml: User configuration and profiles
• sessions.jsonl: Session history in JSON Lines format
• .active.json: Current active session state

Keyboard Shortcuts

• Ctrl+C: Pause the current session (press twice to stop)

Configuration File Example

[defaults]
focus_min = 25
short_min = 5
long_min = 15
cycles = 4
auto_next = true
sound = "bell"
notify = true

[profiles.deepwork]
focus_min = 50
short_min = 10
long_min = 20
cycles = 3

[profiles.quick]
focus_min = 15
short_min = 3
long_min = 10
cycles = 4

Visual Output

The CLI provides rich visual feedback:

• Progress Bar: Real-time progress visualization
• Color Coding:
  • Green: Focus phase
  • Cyan: Short break
  • Blue: Long break
  • Yellow: Paused
• Status Display: Current phase, time remaining, task name, and cycle count
• Statistics Dashboard: Formatted tables with productivity metrics

Development

Project Structure

src/
├── cli/          # Command-line interface and argument parsing
├── core/         # Core business logic and state machine
├── store/        # Configuration and data persistence
├── timer/        # Timer engine and async operations
└── ui/           # Terminal UI and display formatting

Building from Source

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with verbose output
RUST_LOG=debug cargo run -- start

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Roadmap

• System notifications (desktop alerts)
• Sound effects beyond terminal bell
• Web dashboard for statistics
• Integration with task management tools
• Team/shared sessions
• Mobile companion app
• Focus mode hooks (DND mode, app blocking)

Acknowledgments

Built with:

• clap - Command-line argument parsing
• tokio - Async runtime
• indicatif - Progress bars
• chrono - Date and time handling
• serde - Serialization framework