| 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
ttm start myproject
ttm start myproject --note "fix login bug"
ttm status
ttm stop
ttm report
Timer Commands
ttm start <project>
ttm start <project> --note "..."
ttm stop
ttm stop --note "resolved"
ttm status
Log Entries Manually
ttm log myproject 1h30m
ttm log myproject 45m --note "code review"
ttm log myproject 2h --at 09:00
List Entries
ttm list
ttm list --today
ttm list --week
ttm list --project myproject
ttm list --limit 50
Reports
ttm report
ttm report --week
ttm report --month
ttm report --from 2026-03-01 --to 2026-03-20
ttm report --project myproject
Edit and Delete
ttm edit 42 --note "updated"
ttm edit 42 --project otherproject
ttm edit 42 --start 09:00
ttm edit 42 --end 11:30
ttm delete 42
ttm delete 42 --yes
Projects
ttm projects
ttm projects add myproject
ttm projects rename old new
ttm projects delete myproject
Export
ttm export
ttm export --output entries.csv
ttm export --format json
ttm export --week --output week.csv
ttm export --from 2026-03-01 --to 2026-03-31 --output march.json
Statistics
ttm stats
ttm stats --week
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 |