zman

A small timer utility to track how much time you spend on tasks.

Pre-v1 — the CLI may change between releases.

Install

Have zig v0.16.0 installed

git clone https://github.com/defaultgnome/zman
cd zman
zig build
# copy zig-out/bin/zman somewhere on your PATH

Config is stored at the path printed by zman config (typically ~/Library/Application Support/zman.json on macOS).

Usage

zman --help                  # list commands
zman <command> -h            # help for a specific command

Commands

Command	Description
zman	Open full-screen TUI (coming soon)
zman version	Print version
zman config	Print config file path
zman start [name]	Start a timer; Ctrl-C or Esc to stop (Esc only on Windows)
zman stop <name>	Close the last open time entry for a task
zman log <name>	Add a manual clock-in/clock-out entry
zman amend <name> <id>	Edit or remove an existing time entry
zman list	List tasks with total time
zman delete <pattern>	Delete tasks matching a glob pattern
zman merge <from> <to>	Merge time entries from one task into another
zman show <name>	Print full clock-in/clock-out log for a task

zman start

zman start my-task           # named task
zman start                   # auto-named (unnamed-task-1, unnamed-task-2, …)
zman start --last            # restart the last started task
zman start --git             # use current git branch as task name

On Unix, press Ctrl-C or Esc to stop. On Windows, press Esc.

--last and --git cannot be combined with a task name. See zman start -h.

zman stop

Closes the last open clock-out for the given task using the current time. Errors if the task has no entries or the last entry is already closed.

zman stop my-task

zman log

Adds a manual clock-in/clock-out entry. Aborts if the range overlaps an existing entry or is in the future.

zman log my-task --from=09:00 --to=11:30
zman log my-task --from="2026-06-10 09:00" --to="2026-06-10T11:30"

Time formats (local time):

Format	Example
HH:MM	today at 09:00
HH:MM:SS	today at 09:00:00
YYYY-MM-DD HH:MM	full date and time
YYYY-MM-DD HH:MM:SS	full date and time
YYYY-MM-DDTHH:MM	ISO-style date and time
YYYY-MM-DDTHH:MM:SS	ISO-style date and time

See zman log -h.

zman amend

Edits or removes an existing time entry. <id> is the row index shown by zman show (0 is the first entry).

zman amend my-task 0 --from=09:15          # change clock-in
zman amend my-task 0 --to=11:45            # change clock-out
zman amend my-task 0 --from=+0:15          # shift clock-in forward 15 minutes
zman amend my-task 0 --to=-0:30            # shift clock-out back 30 minutes
zman amend my-task 0 --drop                # remove the entry

Accepts the same absolute time formats as zman log, plus relative offsets from the entry's current value: +H:MM, -H:MM, +H:MM:SS, -H:MM:SS.

--drop cannot be combined with --from or --to. At least one of --from, --to, or --drop is required. See zman amend -h.

zman list

zman list                    # name + total time, aligned
zman list --name-only        # one task name per line (useful for scripting)

zman delete

Deletes all tasks whose name matches a glob pattern (* matches any substring). The confirmation prompt defaults to yes — press Enter to proceed.

zman delete "old-feature*"   # delete tasks starting with old-feature
zman delete "*"              # delete every task (prompts for confirmation)
zman delete "*" -y           # delete all, skip confirmation

See zman delete -h.

zman merge

Moves all time entries from <from> into <to>, then removes <from>. Aborts with no changes if any time ranges overlap.

zman merge old-name new-name

On success, prints the merged result (same format as zman show).

zman show

Prints a summary line (total time, date range, day count) and a table of every entry with a # index, clock-in, clock-out, and duration. Open entries show N/A for clock-out and duration.

zman show my-task

Example output:

Task: my-task
Total: 2h 30m  ·  2026-06-10 → 2026-06-14  ·  3 days

#  Clock-in            Clock-out           Duration
0  2026-06-10 09:00    2026-06-10 11:00    2h 0m
1  2026-06-14 08:00    N/A                 N/A

Use the # column as the <id> for zman amend.

fzf recipes

With fzf installed:

# fuzzy-pick a task to inspect
zman show "$(zman list --name-only | fzf)"

# fuzzy-pick a task to stop
zman stop "$(zman list --name-only | fzf)"

# fuzzy-pick a task to delete
zman delete "$(zman list --name-only | fzf)"

# fuzzy-pick from/to for a merge
zman merge \
  "$(zman list --name-only | fzf --prompt="from: ")" \
  "$(zman list --name-only | fzf --prompt="to: ")"

Development

zig build test

Changes

v0.5.0

• Added zman amend — edit clock-in/clock-out on an existing entry, apply relative time offsets, or drop an entry by index

v0.4.0

• Added # index column to zman show output (used as entry id for zman amend)
• Added date range and day count to the zman show summary line

v0.3.0

• Added zman stop — close the last open time entry without running a live timer
• Added zman log — insert a manual clock-in/clock-out range
• Added Esc as a stop key during zman start (Unix: Ctrl-C or Esc; Windows: Esc)

v0.2.0

• Fixed delete confirmation prompt defaults to yes when Enter is pressed ([Y/n])