Task Tracker CLI

A simple yet fully-featured command-line application to track and manage your tasks — built with Java 17 and zero external dependencies.

Tasks are stored locally in a tasks.json file in your working directory, with full support for adding, updating, deleting, and filtering by status.

---

Features

• Add, update, and delete tasks
• Mark tasks as todo, in-progress, or done
• List all tasks or filter by status
• Persistent JSON storage — no database required
• Built entirely with the Java standard library (java.nio, java.time)
• Graceful error handling with descriptive messages

---

Requirements

• Java 17 or higher (JDK for building, JRE for running the JAR)

Verify your installation:

java -version
javac -version

Don't have Java? Download JDK 17+ from Adoptium (free, cross-platform).

---

Installation

Option A — Clone and build from source

# 1. Clone the repository
git clone https://github.com/fs23yayan/task-cli.git
cd task-cli

# 2. Compile
mkdir -p out/classes
javac --release 17 -d out/classes src/main/java/taskcli/*.java

# 3. Package into a JAR
cat > out/MANIFEST.MF << 'EOF'
Manifest-Version: 1.0
Main-Class: taskcli.Main
EOF
jar cfm task-cli.jar out/MANIFEST.MF -C out/classes .

Or simply run the included build script:

chmod +x build.sh && ./build.sh

Option B — Download the pre-built JAR

Download task-cli.jar from the Releases page and run it directly — no compilation needed.

---

Usage

All commands follow this pattern:

java -jar task-cli.jar <command> [arguments]

Add a task

java -jar task-cli.jar add "Buy groceries"
# Output: Task added successfully (ID: 1)

Update a task

java -jar task-cli.jar update 1 "Buy groceries and cook dinner"
# Output: Task updated successfully (ID: 1)

Delete a task

java -jar task-cli.jar delete 1
# Output: Task deleted successfully (ID: 1)

Mark a task as in-progress

java -jar task-cli.jar mark-in-progress 1
# Output: Task 1 marked as [in-progress]

Mark a task as done

java -jar task-cli.jar mark-done 1
# Output: Task 1 marked as [done]

List tasks

# All tasks
java -jar task-cli.jar list

# Only done tasks
java -jar task-cli.jar list done

# Only todo tasks
java -jar task-cli.jar list todo

# Only in-progress tasks
java -jar task-cli.jar list in-progress

Example output:

[1] [done]        Buy groceries and cook dinner  (created: 2024-01-15T09:00:00, updated: 2024-01-15T14:30:00)
[2] [in-progress] Read a book                    (created: 2024-01-15T09:01:00, updated: 2024-01-15T10:00:00)
[3] [todo]        Go for a run                   (created: 2024-01-15T09:02:00, updated: 2024-01-15T09:02:00)

---

Optional: Shell Alias

To avoid typing java -jar task-cli.jar every time, use the included shell wrapper.

macOS / Linux:

chmod +x task-cli

# Run from project directory
./task-cli list

# Or add to PATH for global access
export PATH="$PATH:/path/to/task-cli"
task-cli list

Windows (PowerShell): Create a task-cli.bat file next to the JAR:

@echo off
java -jar "%~dp0task-cli.jar" %*

Then add the folder to your system PATH. After that:

task-cli list
task-cli add "New task"

---

JSON Storage

Tasks are stored in tasks.json in whichever directory you run the command from. The file is created automatically on first use.

[
  {
    "id": 1,
    "description": "Buy groceries and cook dinner",
    "status": "done",
    "createdAt": "2024-01-15T09:00:00",
    "updatedAt": "2024-01-15T14:30:00"
  },
  {
    "id": 2,
    "description": "Read a book",
    "status": "in-progress",
    "createdAt": "2024-01-15T09:01:00",
    "updatedAt": "2024-01-15T10:00:00"
  }
]

Task Properties

Property	Type	Description
id	Integer	Auto-incremented unique identifier
description	String	Short description of the task
status	String	todo · in-progress · done
createdAt	String	ISO-8601 timestamp when the task was created
updatedAt	String	ISO-8601 timestamp of the last modification

---

Project Structure

task-cli/
├── src/
│   └── main/
│       └── java/
│           └── taskcli/
│               ├── Main.java         # CLI entry point and command dispatch
│               ├── Task.java         # Task model with built-in JSON serializer
│               └── TaskStore.java    # File persistence using java.nio
├── build.sh                          # Compile + package script
├── task-cli                          # Shell wrapper (macOS/Linux)
├── task-cli.jar                      # Pre-built runnable JAR
└── README.md

Architecture

• Main.java — Parses positional CLI arguments, dispatches to the correct command handler, and handles all error reporting to stderr.
• Task.java — Defines the task model with a hand-written JSON serializer/deserializer. No Jackson, Gson, or any external library.
• TaskStore.java — Reads and writes tasks.json using java.nio.file.Files. Parses the JSON array by tracking brace depth, correctly handling nested structures and escape sequences.

---

Command Reference

Command	Description
add "<description>"	Create a new task with status todo
update <id> "<description>"	Update the description of an existing task
delete <id>	Permanently remove a task
mark-in-progress <id>	Set task status to in-progress
mark-done <id>	Set task status to done
list	Show all tasks
list todo	Show only tasks with status todo
list in-progress	Show only tasks with status in-progress
list done	Show only tasks with status done

---

Error Handling

The CLI exits with a non-zero code and prints a clear message to stderr for all error conditions:

java -jar task-cli.jar delete 999
# Error: Task not found: 999

java -jar task-cli.jar update abc "test"
# Error: Invalid ID: "abc". Must be a positive integer.

java -jar task-cli.jar list pending
# Error: Unknown filter: "pending". Use: done | todo | in-progress

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: describe your change"
4. Push and open a Pull Request

Please ensure all existing commands still work correctly before submitting.

---

License

This project is licensed under the MIT License. See LICENSE for details.

---

Acknowledgements

Project idea sourced from roadmap.sh — Task Tracker.