Getting Started

Install

Download a binary

Grab the latest release for your platform from GitHub Releases. Extract and move to your PATH:

tar xzf hrs_*_darwin_arm64.tar.gz
sudo mv hrs /usr/local/bin/

Available builds: darwin_amd64, darwin_arm64, linux_amd64, linux_arm64.

Go install

go install github.com/heuwels/hrs@latest

This puts the binary in $(go env GOPATH)/bin. If you get "command not found", add it to your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

For most people, downloading the binary directly is simpler.

Build from source

git clone https://github.com/heuwels/hrs
cd hrs
go build -o hrs .

No CGo — a plain go build works on any platform with no C compiler.

Configuration

hrs stores data in ~/.hrs/hrs.db by default. Override with environment variables:

Variable	Default	Description
HRS_DB	~/.hrs/hrs.db	SQLite database path
HRS_DIR	~/.hrs/	Markdown output directory

Or pass --db / --dir flags to any command.

Quick start

Log an entry

hrs log -c dev -t "built auth flow" -b "oauth2 pkce;token refresh;tests" -e 3

Bullets are separated by semicolons. -e is your estimate of how long this would take a competent developer without AI assistance.

View today's log

hrs ls

Color output in the terminal, markdown when piped. Add --format json for structured output.

Browse with the TUI

hrs tui

Set a goal

hrs goals add "implement oauth2 pkce"
hrs goals done 1 -e 42

See Goals & Strategies for the full guide.

CLI reference

Command	Description
hrs serve	Start the HTTP API server
hrs log -c -t -b -e	Log an entry
hrs ls [date]	List entries (today if omitted)
hrs ls --from --to	List a date range
hrs tui [date]	Interactive terminal explorer
hrs edit <id> [flags]	Update an entry
hrs rm <id>	Delete an entry
hrs export	Export entries as JSON or CSV
hrs goals [action]	Manage daily goals
hrs strategy [action]	Manage strategic goals
hrs categories	List all categories
hrs migrate	Import existing markdown worklogs
hrs docs	Serve the documentation site
hrs version	Print version

Examples

# list entries
hrs ls                                    # today
hrs ls 2026-04-14                         # specific date
hrs ls --format json                      # JSON output
hrs ls --from 2026-04-01 --to 2026-04-15  # date range
hrs ls --from 2026-04-01 --category dev   # filter by category

# edit an entry
hrs edit 42 -t "new title"                # update title
hrs edit 42 -e 2 -c admin                # update hours and category

# export
hrs export --format csv --from 2026-04-01 --to 2026-04-30

# goals
hrs goals add "implement oauth2 pkce"   # add a goal
hrs goals                                # list today's goals
hrs goals done 1 -e 41,42               # complete, link entries

# strategies
hrs strategy add -t "ship v2 auth"       # create strategy
hrs strategy 1                           # view report

Run as a service

macOS (launchd)

cp contrib/hrs.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/hrs.plist

Linux (systemd)

cp contrib/hrs.service ~/.config/systemd/user/
systemctl --user enable --now hrs