Usage Guide

Learn how to use go-pomodoro to run focus sessions, monitor long sitting, and get AI-powered insights.

CLI usage

pomodoro [flags]
pomodoro [command]

Use the commands below to control your focus workflow directly from the terminal.

Start a focus session

pomodoro start

Starts a standard focus timer using built-in break and cycle rules.

pomodoro start -m 25

Runs a session with a custom focus duration in minutes.

Deep work mode

pomodoro deep

Starts a distraction-minimized deep work session for longer, uninterrupted focus.

Monitor long sitting

pomodoro monitor

Continuously tracks activity and alerts you when prolonged sitting is detected.

View session history

pomodoro sessions

Displays recent focus sessions and basic productivity insights.

AI productivity coach

pomodoro coach

Generates personalized focus recommendations based on your recent sessions.

Update the CLI

pomodoro update

Updates go-pomodoro to the latest available version.

Check version

pomodoro version

Prints the currently installed version.

Enable AI features (Groq)

To enable AI coaching and smart break suggestions, set your GROQ API key as an environment variable.

export GROQ_API_KEY="your_api_key_here"

$env:GROQ_API_KEY="your_api_key_here"

Restart your terminal after setting the key.

How breaks are calculated

Break duration and focus cycles automatically adjust based on your session length. Short sessions keep breaks minimal, while longer deep work sessions receive longer recovery periods to reduce fatigue.