Metadata-Version: 2.4
Name: track-cli
Version: 0.2.0
Summary: A simple CLI tool for tracking time spent on tasks
Home-page: https://github.com/sakshamshil/Timetracker
Author: sakshamshil
Author-email: your.email@example.com
Project-URL: Bug Reports, https://github.com/sakshamshil/Timetracker/issues
Project-URL: Source, https://github.com/sakshamshil/Timetracker
Keywords: time tracking,productivity,cli,timesheet
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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+):

```bash
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://pypi.org/project/track-cli/

Alternative install via pip:
```bash
pip install track-cli
# or
pipx install track-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**
```bash
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:

```bash
track update
```

This pulls the latest code from GitHub and reinstalls automatically.

## Uninstalling

```bash
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
```bash
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:**
```bash
track start "Your Task Name" [-f | --force]
```

**Examples:**

**1. Start a new task when no other task is running:**
```bash
track start "Developing a new feature"
```
> **Output:**
> `🟢 Started tracking: 'Developing a new feature'`

**2. Force start a new task when another is already running:**
```bash
track start "Urgent bug fix" --force
```
> **Output:**
> ```
> ✅ Stopped tracking 'Developing a new feature'. Logged 30m.
> 🟢 Started tracking: 'Urgent bug fix'
> ```

---

#### 2. Stop the Current Task
When you have finished working on a task, use the `stop` command.

**Usage:**
```bash
track stop
```
> **Output:**
> `✅ Stopped tracking 'Developing a new feature'. Logged 25m.`

---

#### 3. Pause the Current Task
If you need to take a break, use the `pause` command. You can optionally pass a
reason, which is shown in `track status` and cleared when you resume.

**Usage:**
```bash
track pause [REASON]
```

**Examples:**
```bash
track pause
track pause "lunch break"
```
> **Output:**
> `⏸️ Paused 'Developing a new feature'. (20m logged so far). Reason: lunch break`

---

#### 4. Resume a Paused Task
To continue a task that was previously paused, use the `resume` command.

**Usage:**
```bash
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:**
```bash
track notes "<NOTE_TEXT>"
```

**Example:**
```bash
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:**
```bash
track status
```
> **Output (if a task is running with notes):**
> ```
> 🟢 Active Task: 'Developing a new feature' (15m so far)
>    Notes:
>      - Finished the main logic, now writing tests.
> ```
>
> **Output (if a task is paused):**
> `⏸️ Paused Task: 'Developing a new feature' (20m logged)`
> `⏸️ Paused Task: 'Developing a new feature' (20m logged) - Reason: lunch break`
>
> **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:**
```bash
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:**
```bash
# 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"
```

**Interactive Easy Mode**

Run `track add` with no arguments to be guided through adding an entry. It
prompts for the activity name (offering the last logged activity as the
default), the start time, and then either an end time or a duration. Invalid
input is re-prompted, and the entry is saved directly once valid.

```bash
track add
```
> **Output:**
> ```
> Activity name []: Client call
> Start time (e.g. 'today 10am', 'yesterday 3pm'): 22-07-2025 15:00
> End time (leave blank to use a duration) []:
> Duration (e.g. '1h', '30m', '1h30m'): 45m
> ✅ Logged 'Client call' for 45m.
> ```

You can also pass the activity up front and be prompted only for the times:

```bash
track add "Client call"
```

---

#### 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:**
```bash
track log [WHEN]
```
The `WHEN` argument can be:
- `today` (default)
- `yesterday`
- A date in `DD-MM-YYYY` format (e.g., `19-07-2025`)

**Example:**
```bash
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                                  25m
>       - Finished the main logic.
> 1     11:05:00   11:35:30   Team meeting                                              30m
> --------------------------------------------------------------------------------
> Total time for 2025-07-19: 55m
> ```

---

#### 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:**
```bash
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:
```bash
track log
```
> **Output:**
> ```
> --- Time Log for 2025-07-26 ---
> ID    Start      End        Activity                  Duration
> ----------------------------------------------------------------------
> 0     09:00:00   10:00:00   Team Stand-up               1h 0m
> 1     10:15:00   11:00:00   Code Review                   45m
> ----------------------------------------------------------------------
> Total time for 2025-07-26: 1h 45m
> ```

Now, remove the "Team Stand-up" entry using its ID:
```bash
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:**
```bash
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:
```bash
track log
```
> **Output:**
> ```
> --- Time Log for 2025-09-26 ---
> ID    Start      End        Activity                  Duration
> ----------------------------------------------------------------------
> 0     09:00:00   10:00:00   Team Stand-up               1h 0m
> 1     10:15:00   11:00:00   Code Review                   45m
> ----------------------------------------------------------------------
> Total time for 2025-09-26: 1h 45m
> ```

Now, edit the "Code Review" entry using its ID:
```bash
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:**
```bash
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:*
    ```bash
    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:*
    ```bash
    track alias remove @docs
    ```
    > **Output:**
    > `✅ Alias '@docs' removed.`

-   **`list`**
    Shows all aliases you have configured.

    *Example:*
    ```bash
    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:**
```bash
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:**
```bash
track backdate <DURATION> "<ACTIVITY>"
```

**Duration Format:**
-   `1h` (1 hour)
-   `30m` (30 minutes)
-   `2h15m` (2 hours and 15 minutes)

**Example:**
```bash
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:**
```bash
# Add a memo
track memo "<TEXT>"

# List all memos
track memo

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

# Export all memos to a file (csv or xlsx)
track memo --export <csv|xlsx>
```

**Examples:**

**1. Add a memo:**
```bash
track memo "Fix bug in timelogger"
```
> **Output:**
> `✅ Memo added.`

**2. List all memos:**
```bash
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
> ----------------------------------------------------------------------
> ```

Long memos are shown in full: the text wraps onto continuation lines aligned
under the **Note** column instead of being cut off with an ellipsis.
> ```
> ID    Created              Note
> ----------------------------------------------------------------------
> 0     2025-12-23 15:30     This is a much longer memo that wraps onto
>                            multiple lines aligned under the Note column
> ----------------------------------------------------------------------
> ```

**3. Remove a memo:**
```bash
track memo --remove 0
```
> **Output:**
> `✅ Memo removed: 'Fix bug in timelogger'`

**4. Export all memos:**
```bash
track memo --export csv
```
> **Output:**
> `✅ Successfully exported all memos to .../exports/timetrack_memos_20251223_153000.csv`

The file is written to the `exports/` directory with a timestamped name and
contains the `text` and `created_at` of every memo. Use `--export xlsx` for an
Excel file. Exporting with no memos reports `❗ No memos to export.`

---

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

**Usage:**
```bash
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:**
```bash
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:**
```bash
track export [--format FORMAT]
```
The `FORMAT` can be `csv` or `xlsx` (default is `xlsx`).

**Example:**
```bash
track export --format csv
```
> **Output:**
> `✅ Successfully exported all data to /path/to/project/exports/timetrack_export_20250720_221403.csv`

---

#### 17. Generate the Dashboard (local)

Build the self-contained dashboard HTML locally without deploying it. Useful
for previewing or designing the page. The file inlines all CSS/JS (no CDN),
so it opens from anywhere offline.

**Usage:**
```bash
track dashboard [--days N] [--out DIR]
```
- `--days` (default 30): number of trailing days to include.
- `--out` (default `~/.timetrack/dashboard`): output directory.

**Example:**
```bash
track dashboard --days 14 --out ./preview
```
> **Output:**
> `✅ Dashboard written to ./preview/index.html`

---

#### 18. Sync / Deploy the Dashboard

Deploy your dashboard to a static host so you can view "how your days went"
from any device. The first run launches an interactive setup wizard that asks
for your host (Vercel), token, project name, an optional custom domain, and
whether to protect the data with a passphrase (optional, not mandatory). After
that, every run re-deploys to the **same project → same URL, updated in place**.

**Usage:**
```bash
track sync [--install-cron] [--edit]
```
- `--install-cron`: also install a daily scheduled job (launchd on macOS,
  crontab on Linux) so the dashboard refreshes automatically.
- `--edit`: re-run setup to change the existing config (prompts are
  prefilled with current values; leave a field empty to keep it).

**First run (wizard):**
```bash
track sync
```
> `Set up remote dashboard — deploy your time review to a static host.`
> `Host: vercel (only backend in this version)`
> `✅ Sync configuration saved.`
> `✅ Dashboard live at: https://track-dash.vercel.app`

**Later runs:**
```bash
track sync
```
> `✅ Dashboard live at: https://track-dash.vercel.app`

**Privacy:** if you choose passphrase protection during setup, the dashboard
data is AES-GCM encrypted before it leaves your machine; the host only serves
ciphertext, and you type the passphrase in the browser to view it. Without it,
the data is plaintext (protected only by URL obscurity).

---

### 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.
