terminal-time-tracker

name	terminal-time-tracker
description	Track time spent on projects from the terminal. Use when starting/stopping timers, logging time, viewing daily or weekly reports, or exporting time data. Triggers include "track time", "time tracker", "ttm", "log hours", "time report", "how much time", "start timer".

terminal-time-tracker

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

Quick Start

# 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

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

# 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

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

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

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

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

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

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