hrs / docs

Goals & Strategies

Two layers: daily goals for what you want done today, and strategies for things that span days or weeks.

Goals link to entries (work you've logged) and to strategies. Hours roll up from entries through goals into strategy reports.

strategy: "ship v2 auth"
  ├── goal: "implement oauth2 pkce" (2026-04-14) → entries #41, #42
  ├── goal: "add token refresh" (2026-04-15) → entry #45
  └── goal: "write integration tests" (2026-04-16) → entry #48

Daily goals

Set goals for today

hrs goals add "implement oauth2 pkce"
hrs goals add -d 2026-04-18 "review deployment docs"
hrs goals add -s 1 "write migration scripts"
hrs goals add -s 1 --ticket PROMO-123 "ship pat creation"

-d sets the date (defaults to today). -s links the goal to a strategy. --ticket attaches an external ticket reference (see ticket references). Place flags before the goal text — Go's flag parser stops at the first positional argument.

List goals

hrs goals                    # today's goals
hrs goals -d 2026-04-18     # specific date
hrs goals --format json      # machine-readable

Complete a goal

hrs goals done 1             # mark goal #1 complete
hrs goals done 1 -e 41,42   # complete and link entries #41 and #42

Linking entries connects the work you logged to the goal it achieved.

Link entries to a goal

hrs goals link 1 -e 41,42   # link entries without completing

Reopen or delete

hrs goals undo 1             # reopen a completed goal
hrs goals rm 1               # delete a goal

Strategies

Strategies span multiple days. Daily goals link up to them, and hrs rolls up progress across all linked goals.

Create a strategy

hrs strategy add -t "ship v2 auth" -desc "oauth2, token refresh, integration tests"
hrs strategy add -t "ship pat creation" --ticket PROMO-150

Title can also be passed as a positional argument:

hrs strategy add "ship v2 auth"

--ticket attaches an external ticket reference (see ticket references).

List strategies

hrs strategy                         # all strategies
hrs strategy -status active          # filter by status
hrs strategy --format json           # machine-readable

View a strategy report

hrs strategy 1                       # shorthand for report
hrs strategy report 1                # explicit
hrs strategy report 1 --format json  # machine-readable

The report shows goal completion (e.g. 3/5 done), total hours rolled up from linked entries, and a list of all goals.

Manage lifecycle

hrs strategy done 1          # mark as completed
hrs strategy archive 1       # pause (archive)
hrs strategy reopen 1        # set back to active
hrs strategy edit 1 -t "new title" -desc "updated description"
hrs strategy rm 1            # delete (unlinks goals, doesn't delete them)

Linking it all together

The typical workflow:

  1. Create a strategy for a multi-day initiative
  2. Each morning, set daily goals linked to that strategy
  3. As you complete work, log entries with hrs log
  4. Mark goals done and link the entries that achieved them
  5. Check strategy reports to see overall progress
# 1. create strategy
hrs strategy add -t "migrate to postgres"

# 2. set today's goals, linked to the strategy (-s flag)
hrs goals add "schema migration scripts" -s 1
hrs goals add "update connection pooling" -s 1

# 3. log work as you go
hrs log -c dev -t "wrote migration scripts" -b "up/down for users table;seed data" -e 2

# 4. complete goal, link the entry
hrs goals done 1 -e 50

# 5. check progress
hrs strategy 1

Link goals to a strategy with -s on the CLI or strategy_id via HTTP.

Ticket references

Both goals and strategies can carry an optional ticket_ref — a free-form string pointing at an external work item. Anything works:

hrs strategy add -t "ship pat creation" --ticket PROMO-150
hrs goals add -s 1 --ticket PROMO-151 "filament ui"
hrs goals edit 5 --ticket ""    # clear

Set the ticket on the strategy, the goal, or both — the filter ORs across them, so a goal under a PROMO-150 strategy still matches --ticket PROMO even when the goal itself carries no ticket.

Filtering entries by ticket

hrs ls and hrs export accept --ticket to find every entry linked (through a goal) to a goal or strategy whose ticket matches the prefix:

# every entry tagged to a Promotheus ticket — for an R&D claim
hrs export --ticket PROMO --from 2026-01-01 --to 2026-12-31 --format csv

# narrow to one ticket
hrs ls --ticket PROMO-150 --from 2026-04-01

# combine with category
hrs export --ticket PROMO --category dev --format json

The match is a SQL LIKE prefix by default — --ticket PROMO becomes PROMO%. Include % or _ in your value to override.

Ticket filtering only sees entries that are linked to a goal. If you want work to count for a ticket-scoped report, complete the goal with -e <entry_ids> (or hrs goals link) so the link is recorded.

TUI support

The TUI has a dedicated goals view. Press tab to switch between entries and goals. See TUI explorer for all keybindings.

← Getting Started API Reference →