track-cli 0.1.0

A simple CLI tool for tracking time spent on tasks

track: A Simple CLI Time Tracker

A fast and simple command-line tool to track the time you spend on different tasks.

Installation

One-line install (requires Python 3.8+):

curl -fsSL https://raw.githubusercontent.com/sakshamshil/Timetracker/main/install-remote.sh | bash

This will:

• Check for Python 3.8+
• Install pipx if not present
• Clone the repo to ~/.timetrack-repo
• Install the track command globally

Also available on PyPI: https://test.pypi.org/project/timetrack-cli/

Requirements

• OS: Linux, macOS, or WSL (Windows Subsystem for Linux)
• Python: 3.8 or higher
• Tools: curl, git, bash

Troubleshooting

"track: command not found"

• Restart your terminal or run: source ~/.bashrc (or ~/.zshrc for zsh)

Permission errors

• Run: python3 -m pipx ensurepath then restart terminal

Behind a corporate proxy

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
curl -fsSL https://raw.githubusercontent.com/sakshamshil/Timetracker/main/install-remote.sh | bash

Updating

Run the built-in update command:

track update

This pulls the latest code from GitHub and reinstalls automatically.

Uninstalling

pipx uninstall timetrack-cli  # or track
rm -rf ~/.timetrack-repo      # remove source code
rm -rf ~/.timetrack           # remove data files

How to Use

All commands are run from your terminal.

General Syntax

track [COMMAND]

---

Commands

1. Start a Task

To begin tracking time for a new activity, use the start command followed by the name of the task.

If a task is already running, you can use the -f or --force flag to automatically stop the current task and start the new one.

Usage:

track start "Your Task Name" [-f | --force]

Examples:

1. Start a new task when no other task is running:

track start "Developing a new feature"

Output: 🟢 Started tracking: 'Developing a new feature'

2. Force start a new task when another is already running:

track start "Urgent bug fix" --force

Output:

✅ Stopped tracking 'Developing a new feature'. Logged 30 minutes.
🟢 Started tracking: 'Urgent bug fix'

---

2. Stop the Current Task

When you have finished working on a task, use the stop command.

Usage:

track stop

Output: ✅ Stopped tracking 'Developing a new feature'. Logged 25 minutes.

---

3. Pause the Current Task

If you need to take a break, use the pause command.

Usage:

track pause

Output: ⏸️ Paused 'Developing a new feature'.

---

4. Resume a Paused Task

To continue a task that was previously paused, use the resume command.

Usage:

track resume

Output: 🟢 Resumed tracking: 'Developing a new feature'

---

5. Add a Note to the Current Task

While a task is running, you can add multiple notes to it. This is useful for logging details, progress, or any other relevant information.

Usage:

track notes "<NOTE_TEXT>"

Example:

track notes "Finished the main logic, now writing tests."

Output: ✅ Note added.

---

6. Check the Current Status

To see which task is currently running and for how long, use the status command. The output will also include any notes you've added.

Usage:

track status

Output (if a task is running with notes):

🟢 Active Task: 'Developing a new feature' (15 minutes so far)
   Notes:
     - Finished the main logic, now writing tests.

Output (if a task is paused): ⏸️ Paused Task: 'Developing a new feature' (20 minutes logged)

Output (if no task is running): ⚪ No task is currently running.

---

7. Add a Manual Time Entry

For moments when you forget to use start and stop, the add command lets you log time retrospectively. It's a flexible tool that accepts a variety of date, time, and duration formats.

Usage:

track add "<ACTIVITY>" --start "<TIME>" [--end "<TIME>" | --for "<DURATION>"]

Arguments & Options:

• "<ACTIVITY>" (Required): The name of the task you are logging.
• --start "<TIME>" (Required): The start time of the task.
• --end "<TIME>" (Optional): The end time of the task. You must provide either --end or --for.
• --for "<DURATION>" (Optional): The duration of the task. You must provide either --end or --for.

Key Features:

• You must provide a start time and either an end time or a duration, but not both.
• The command intelligently parses a wide range of time and duration formats.

Time Format Examples (--start and --end): The time parser is highly flexible. Here are some of the formats you can use:

• Relative Dates: today 10:00, yesterday 3pm, today 14:30:15
• Absolute Dates: 25-07-2025 10:00, 2025-07-25 14:30, July 25 2025 2:30pm
• Time Only: 10:00 (defaults to today), 3:15pm

Duration Format Examples (--for): Provide durations in a simple, combined format:

• 1h (1 hour)
• 30m (30 minutes)
• 2h15m (2 hours and 15 minutes)
• 90m (90 minutes)

Examples:

# Log a 2-hour task that happened today
track add "Team Retrospective" --start "today 2pm" --for "2h"

# Log a task from yesterday with a specific start and end time
track add "Design review" --start "yesterday 10:00" --end "yesterday 11:30"

# Log a task with a specific date
track add "Client call" --start "22-07-2025 15:00" --for "45m"

---

8. View Time Logs

To see a summary of all tasks you have logged, use the log command. By default, it shows today's log. Any notes associated with a task will be displayed beneath it.

Usage:

track log [WHEN]

The WHEN argument can be:

• today (default)
• yesterday
• A date in DD-MM-YYYY format (e.g., 19-07-2025)

Example:

track log yesterday

Output:

--- Time Log for 2025-07-19 ---
ID    Start      End        Activity                                             Duration
--------------------------------------------------------------------------------
0     10:30:15   10:55:20   Developing a new feature                               25 min
      - Finished the main logic.
1     11:05:00   11:35:30   Team meeting                                           30 min
--------------------------------------------------------------------------------
Total time for 2025-07-19: 55 minutes

---

9. Remove a Log Entry

To remove a specific time entry from your log, use the remove command with the ID of the entry you want to delete. You can find the ID for each entry by running track log.

Usage:

track remove <ID> [--when WHEN]

Arguments & Options:

• <ID> (Required): The numerical ID of the log entry to be removed.
• --when WHEN (Optional): Specifies the day from which to remove the entry. It accepts the same formats as the log command (today, yesterday, or DD-MM-YYYY). Defaults to today.

Example: First, view the log to find the ID of the entry you want to remove:

track log

Output:

--- Time Log for 2025-07-26 ---
ID    Start      End        Activity                  Duration
----------------------------------------------------------------------
0     09:00:00   10:00:00   Team Stand-up             60 min
1     10:15:00   11:00:00   Code Review               45 min
----------------------------------------------------------------------
Total time for 2025-07-26: 1h 45m

Now, remove the "Team Stand-up" entry using its ID:

track remove 0

Output: ✅ Removed entry: 'Team Stand-up'

---

10. Edit a Log Entry

To edit a specific time entry from your log, use the edit command with the ID of the entry you want to change. You can find the ID for each entry by running track log.

Usage:

track edit <ID> [--when WHEN]

Arguments & Options:

• <ID> (Required): The numerical ID of the log entry to be edited.
• --when WHEN (Optional): Specifies the day from which to edit the entry. It accepts the same formats as the log command (today, yesterday, or DD-MM-YYYY). Defaults to today.

Example: First, view the log to find the ID of the entry you want to edit:

track log

Output:

--- Time Log for 2025-09-26 ---
ID    Start      End        Activity                  Duration
----------------------------------------------------------------------
0     09:00:00   10:00:00   Team Stand-up             60 min
1     10:15:00   11:00:00   Code Review               45 min
----------------------------------------------------------------------
Total time for 2025-09-26: 1h 45m

Now, edit the "Code Review" entry using its ID:

track edit 1

Output:

Activity [Code Review]:
Start Time [2025-09-26T10:15:00]: 2025-09-26T10:20:00
End Time [2025-09-26T11:00:00]:
✅ Entry 1 updated.

---

11. Manage Task Aliases

To save time on frequently used task names, you can create aliases.

Usage:

track alias [COMMAND]

Commands:

• add <ALIAS_NAME> "<FULL_ACTIVITY>" Adds a new alias or updates an existing one. It's recommended to prefix aliases with @ to distinguish them from regular task names.

  Example:

  track alias add @docs "Writing documentation for Project Phoenix"
  

  Output: ✅ Alias '@docs' set to 'Writing documentation for Project Phoenix'.

• remove <ALIAS_NAME> Removes a specified alias.

  Example:

  track alias remove @docs
  

  Output: ✅ Alias '@docs' removed.

• list Shows all aliases you have configured.

  Example:

  track alias list
  

  Output:

  --- Configured Aliases ---
  @docs -> Writing documentation for Project Phoenix
  @projx -> Internal Project Phoenix - Scoping
  

---

12. Start the Previous Task

Quickly restart the last task you logged without typing the full name.

Usage:

track prev

Output: 🟢 Started tracking: 'Team meeting'

---

13. Backdate a Task

If you just finished a task but forgot to track it, use backdate to quickly log it by specifying how long you spent. The end time is set to "now" and the start time is calculated automatically.

Usage:

track backdate <DURATION> "<ACTIVITY>"

Duration Format:

• 1h (1 hour)
• 30m (30 minutes)
• 2h15m (2 hours and 15 minutes)

Example:

track backdate 2h "Team meeting"

Output: ✅ Logged 'Team meeting' for 2h 0m.

---

14. Global Memos

Unlike task notes (which are tied to a running task), memos are standalone notes you can add anytime. Use them for quick reminders, TODOs, or anything you want to jot down.

Usage:

# Add a memo
track memo "<TEXT>"

# List all memos
track memo

# Remove a memo by ID
track memo --remove <ID>

Examples:

1. Add a memo:

track memo "Fix bug in timelogger"

Output: ✅ Memo added.

2. List all memos:

track memo

Output:

--- Memos ---
ID    Created              Note
----------------------------------------------------------------------
0     2025-12-23 15:30     Fix bug in timelogger
1     2025-12-23 16:00     Review PR #42
----------------------------------------------------------------------

3. Remove a memo:

track memo --remove 0

Output: ✅ Memo removed: 'Fix bug in timelogger'

---

15. Update the Application

Keep your installation up to date by pulling the latest changes from GitHub and reinstalling.

Usage:

track update

What it does:

1. Checks for uncommitted local changes (fails if found)
2. Runs git pull origin main
3. Reinstalls with pipx reinstall track (or pip install -e . as fallback)

Example:

track update

Output (when updates available):

✅ Updated successfully!
Updating 508fbee..a1b2c3d
Fast-forward
 timetrack/core.py | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

Output (when already up to date): ✅ Already up to date. No changes to pull.

Output (when you have uncommitted changes): ❗ Error: You have uncommitted changes. Please commit or stash them first.

---

16. Export All Data

To export your entire time log history to a file, use the export command. The exported file will include a notes column where multiple notes are separated by newlines.

Usage:

track export [--format FORMAT]

The FORMAT can be csv or xlsx (default is xlsx).

Example:

track export --format csv

Output: ✅ Successfully exported all data to /path/to/project/exports/timetrack_export_20250720_221403.csv

---

Data and Export Files

• Log Data: The application stores its data in the ~/.timetrack directory.
  • timelog.json: A persistent log of all your completed time entries.
  • state.json: A temporary file that only exists when a task is actively being tracked or paused.
  • config.json: Stores your task aliases.
  • memos.json: Stores your global memos.
• Exported Files: All exported files are saved in the project/exports/ directory within the project folder.