terminal-time-tracker

# terminal-time-tracker

CLI tool for tracking time on projects with start/stop timers, manual logging, and reports.

## Quick Start

```bash
# Start a timer
ttm start myproject

# Start with a note
ttm start myproject --note "fix login bug"

# Check what is running
ttm status

# Stop the timer
ttm stop

# View today's report
ttm report
```

## Timer Commands

```bash
ttm start <project>              # start timer for project
ttm start <project> --note "..."  # start with a note
ttm stop                         # stop running timer
ttm stop --note "resolved"       # add note when stopping
ttm status                       # show running timer and elapsed time
```

## Log Entries Manually

```bash
# Duration formats: 30m, 1h, 1h30m, 90m
ttm log myproject 1h30m
ttm log myproject 45m --note "code review"
ttm log myproject 2h --at 09:00   # logged at specific start time
```

## List Entries

```bash
ttm list                         # recent entries (latest 20)
ttm list --today                 # today only
ttm list --week                  # this week
ttm list --project myproject     # filter by project
ttm list --limit 50              # show more entries
```

## Reports

```bash
ttm report                       # today
ttm report --week                # current week
ttm report --month               # current month
ttm report --from 2026-03-01 --to 2026-03-20
ttm report --project myproject   # daily breakdown for one project
```

## Edit and Delete

```bash
ttm edit 42 --note "updated"          # update note
ttm edit 42 --project otherproject    # move to different project
ttm edit 42 --start 09:00             # change start time
ttm edit 42 --end 11:30               # change end time
ttm delete 42                         # delete with confirmation
ttm delete 42 --yes                   # delete without prompt
```

## Projects

```bash
ttm projects                          # list all projects with totals
ttm projects add myproject            # create project
ttm projects rename old new           # rename project
ttm projects delete myproject         # delete (prompts if has entries)
```

## Export

```bash
ttm export                            # CSV to stdout
ttm export --output entries.csv       # CSV to file
ttm export --format json              # JSON output
ttm export --week --output week.csv   # this week only
ttm export --from 2026-03-01 --to 2026-03-31 --output march.json
```

## Statistics

```bash
ttm stats                             # all-time totals, streaks, top projects
ttm stats --week                      # weekly bar chart
```

## CLI Reference

| Command | Description |
|---|---|
| `start <project>` | Start timer for project |
| `stop` | Stop running timer |
| `status` | Show running timer |
| `log <project> <duration>` | Manually log completed entry |
| `list` | List entries |
| `report` | Aggregated report by project |
| `edit <id>` | Edit entry fields |
| `delete <id>` | Delete entry |
| `projects` | List and manage projects |
| `export` | Export entries to CSV or JSON |
| `stats` | Statistics and streaks |

## Duration Format

| Input | Parsed as |
|---|---|
| `30m` | 30 minutes |
| `1h` | 1 hour |
| `1h30m` | 1 hour 30 minutes |
| `90m` | 90 minutes (1h 30m) |
| `2h15m` | 2 hours 15 minutes |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `TTM_DB_PATH` | `~/.local/share/terminal-time-tracker/db.sqlite` | SQLite database path |
| `TTM_NO_COLOR` | `0` | Disable ANSI color (1 to disable) |
| `TTM_DEBUG` | `0` | Enable debug logging (1 to enable) |

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | No data found |
| 2 | Timer state error (already running or not running) |
| 3 | Runtime error |