everhour-cli

Everhour time tracking CLI + TUI (Rust, ratatui) with Linear task integration.

Install

Requires the Rust toolchain (rustup: https://rustup.rs).

# straight from GitHub
cargo install --git https://github.com/lpwanw/everhour-cli

# or from a local clone
git clone https://github.com/lpwanw/everhour-cli
cd everhour-cli
cargo install --path .

Installs the everhour binary into ~/.cargo/bin (make sure it is on your PATH).

Then set your API key (Everhour → My Profile → API token):

export EVERHOUR_API_KEY="your-key"   # add to ~/.zshrc
# or persist it in the config file instead:
everhour config --api-key <key>

A regular member API key is enough — no admin scope needed.

Update

everhour update

This reinstalls the latest version from GitHub (runs cargo install --git https://github.com/lpwanw/everhour-cli --force for you).

Once a day, everhour also checks GitHub for a newer version and prints a notice when one is available (3-second timeout, silent when offline). Disable it with:

everhour config --update-check false

Manual alternative from a local clone:

cd everhour-cli && git pull && cargo install --path . --force

Uninstall

cargo uninstall everhour-cli

# optional: remove config (api key, week start)
rm -rf "$HOME/Library/Application Support/everhour-cli"   # macOS
rm -rf ~/.config/everhour-cli                             # Linux

Remove the EVERHOUR_API_KEY line from your shell profile if you added one.

Configuration

Config lives at ~/Library/Application Support/everhour-cli/config.toml on macOS, ~/.config/everhour-cli/config.toml on Linux. Reports start the week on Monday by default (Everhour's UI defaults to Sunday); change with:

everhour config --week-start sunday

CLI

everhour                  # launch the TUI
everhour status           # current timer
everhour start BE-1973    # start timer (Linear number, name fragment, or li:<id>)
everhour stop
everhour tasks <query>    # search Linear-connected tasks (server-side)
everhour report [--last | --week -2]
everhour comment "did X"  # set comment on the running timer's entry
everhour comment "did X" --task li:<id> --date 2026-07-10
everhour config           # show config (key masked)
everhour skill install    # install the Claude Code skill (global or project)

Claude Code skill

Install a Claude Code skill that drives this CLI for your Everhour workflows (start/stop timers, comments, weekly report) with Linear task resolution:

everhour skill install --global    # ~/.claude/skills/everhour  (all projects)
everhour skill install --project   # ./.claude/skills/everhour  (this repo only)
everhour skill install             # prompts for scope

The skill is embedded in the binary, so it ships and versions with every install. Reinstalling overwrites the skill (and removes the old curl-based scripts if present). Start a new Claude Code session after installing.

TUI

Two tabs — [1] Report (default) and [2] Tasks — switched only with 1/2. Running timer always shown in the header.

Report tab

Keys	Action
j/k, gg/G, ctrl-d/ctrl-u	move / top / bottom / half-page
l / Enter	open entry detail (issue + full comment)
h / Esc	back to the entry list
i / e (in detail), c (in list)	edit the comment
[ / ]	previous / next week

Comment editor

Vim-style: h j k l 0 $ w b gg G motions, i a I A o O enter insert, x dd D delete, Esc back to normal, :w save & return to list, :q cancel.

Tasks tab

Keys	Action
/	search tasks (type query, Enter searches server-side)
j/k, gg/G	move
Enter	start timer on selected task

On both tabs: s stop timer · r refresh · q quit. Comment editing lives only on the Report tab.

Notes

• Uses member-scope endpoints (/users/me/time), so a regular member API key works.
• Task search hits GET /tasks/search on demand — nothing is bulk-loaded upfront.
• Linear tasks come from Everhour projects synced from Linear (ids prefixed li:).

Contributing

Contributions are welcome. Fork the repo, create a branch, and open a pull request. Please run cargo test and cargo clippy before submitting.

License

Licensed under the MIT License.