🍅 Pomodoro CLI Manager (pcli)

A lightweight, zero-dependency Pomodoro timer and task manager built entirely with native Node.js APIs. Manage your daily tasks, run focused work sessions, and maintain a persistent productivity history directly from your terminal.

Designed for developers, students, and productivity enthusiasts who prefer staying inside the command line.

✨ Features

• Daily Task Boards — Automatically organizes tasks by date so each day starts with a clean workspace.
• Persistent History — Stores all tasks and completed Pomodoro sessions locally in your home directory (~/.pcli/tasks.json).
• Interactive Pomodoro Timer — Run customizable focus and break sessions from the terminal.
• Cross-Platform Audio Alerts — Plays a bundled alarm.wav using native operating system audio capabilities on Windows, macOS, and Linux.
• Enum-Driven Status Management — Move tasks explicitly into designated lifecycles (todo, working, done).
• Zero Dependencies — Built using only Node.js core modules (fs, path, os, readline, and child_process).
• Global CLI Access — Install once and use from anywhere.

📦 Installation

Install globally from npm:

npm install -g @codewithnuh/pcli

Verify installation:

pcli help

🚀 Quick Start

Create a task:

pcli add "Build authentication middleware"

Explicitly change its status:

pcli status 1 working

Start a Pomodoro session:

pcli start 1

View today's tasks:

pcli list

🛠 Commands

| Command | Description | | --- | --- | | pcli add "title" | Add a new task | | pcli list | Show today's tasks | | pcli history | View complete task history | | pcli edit <id> "title" | Update a task title | | pcli status <id> <target> | Set explicit status (todo | working | done) | | pcli delete <id> | Delete a task | | pcli start <id> | Start a Pomodoro session | | pcli clean | Remove all stored tasks | | pcli help | Display help information |

📋 Usage Examples

Adding Tasks

Create a new task for today:

pcli add "Build authentication middleware"

Output:

✔ Task added successfully! [ID: 1]

Create another task:

pcli add "Design dashboard layout"

Output:

✔ Task added successfully! [ID: 2]

Viewing Today's Tasks

Display all tasks created today:

pcli list

Example output:

📅 Today's Tasks (2026-06-25)

  ID: 1 | ⏳ [TODO] - Build authentication middleware (0 🍅 completed)
  ID: 2 | ✅ [DONE] - Design dashboard layout (2 🍅 completed)

Only tasks from the current date are displayed, keeping your workspace focused and uncluttered.

Updating Task Status

Update an active lifecycle state explicitly using one of the prebuilt system enums: todo, working, or done.

Move to Working state

pcli status 1 working

Output:

✔ Task 1 status updated to: IN-PROGRESS

Complete a task

pcli status 1 done

Output:

✔ Task 1 status updated to: COMPLETED

💡 Passing any value outside of todo, working, or done will safely reject the input with a helpful validation warning without modifying your database.

Editing Tasks

Rename a task by ID:

pcli edit 1 "Build JWT authentication middleware"

Output:

✔ Task 1 updated.

Deleting Tasks

Remove a task permanently:

pcli delete 2

Output:

✔ Task 2 removed.

⏱ Pomodoro Sessions

Start a Pomodoro session:

pcli start 1

The CLI will prompt for durations:

Focus duration in minutes (Default: 25):
Break duration in minutes (Default: 5):

Press Enter to accept the defaults or provide custom values.

Example:

Focus duration in minutes (Default: 25): 50
Break duration in minutes (Default: 5): 10

Focus Phase

After configuration:

🚀 Starting work block for: "Build JWT authentication middleware"

⏳ FOCUS TIME: left...

The task is automatically marked as:

IN-PROGRESS

Focus Completion

When the timer reaches zero:

🎉 Work interval complete! Time for a break.

At the same moment:

• alarm.wav is played.
• Pomodoro completion count increases by 1.
• Break timer begins automatically.

Break Phase

Example:

⏳ BREAK TIME: left...

When the break ends:

💪 Break over! Run `pcli start 1` to launch another block.

📜 Historical Archive

View your complete productivity history:

pcli history

Example output:

📜 Historical Task Archive

▶ 2026-06-25
  [IN-PROGRESS] ID 1: Build JWT authentication middleware (1 mins/sessions)
  [COMPLETED] ID 2: Design dashboard layout (2 mins/sessions)

▶ 2026-06-24
  [COMPLETED] ID 3: Configure PostgreSQL Docker container (4 mins/sessions)

Tasks are automatically grouped by date and sorted from newest to oldest.

🧹 Resetting All Data

Remove every task and Pomodoro record:

pcli clean

Confirmation prompt:

WARNING Are you sure you want to wipe out ALL history? (y/N):

Type:

y

to permanently clear the database.

📂 Data Storage

All data is stored locally:

~/.pcli/tasks.json

Examples:

Linux/macOS

/home/username/.pcli/tasks.json

Windows

C:\Users\Username\.pcli\tasks.json

No cloud services, tracking, or external databases are used.

📄 License

Released under the MIT License.

See the LICENSE file for details.