harvest-tui

README

Harvest TUI Time Tracker

A terminal-based time tracking application that connects to the Harvest API v2, allowing users to manage their daily time entries from the CLI.

Planet Argon has been a long-time customer of Harvest and our software engineers wanted to build a tool for tracking client billables from the command line. This is an open source project that integrates with the Harvest API — there is no collaboration with or endorsement by either party.

Time Sheet view

Add/Edit Time Entry

Help Menu

Installation

Download a Release Binary (Recommended)

Download the latest binary for your platform from the Releases page.

Or use curl to download directly (example for macOS Apple Silicon):

curl -sL https://github.com/planetargon/harvest-tui/releases/latest/download/harvest-tui_darwin_arm64.tar.gz | tar xz
sudo mv harvest-tui /usr/local/bin/

Install with Go

go install github.com/planetargon/harvest-tui/cmd/harvest-tui@latest

The binary is installed to ~/go/bin. If that directory isn't already on your $PATH, add it:

export PATH="$HOME/go/bin:$PATH"

Otherwise, you can run it directly with ~/go/bin/harvest-tui.

Build from Source

1. Clone this repository:

   git clone https://github.com/planetargon/harvest-tui.git
   cd harvest-tui
   

2. Build the application:

   make build
   

The binary will be created at bin/harvest-tui.

Updating

• Release binary: Download the latest version from the Releases page and replace the existing binary.
• Go install: Run go install github.com/planetargon/harvest-tui/cmd/harvest-tui@latest again.
• Build from source: Pull the latest changes and rebuild:

  git pull
  make build
  

Configuration

Getting Harvest API Credentials

1. Log into your Harvest account
2. Go to Settings → Integrations → Developers
3. Create a new Personal Access Token
4. Note your Account ID and Access Token

Setup Config File

1. Copy the example config:

   mkdir -p ~/.config/harvest-tui
   cp config.example.toml ~/.config/harvest-tui/config.toml
   

2. Edit ~/.config/harvest-tui/config.toml with your credentials:

   [harvest]
   account_id = "YOUR_ACCOUNT_ID"
   access_token = "YOUR_ACCESS_TOKEN"
   

Usage

Launch the application:

harvest-tui

Keybindings

Navigation

Key	Action
↑ / k	Move selection up
↓ / j	Move selection down
← / h	Previous day
→ / l	Next day
t	Jump to today

Time Entry Actions

Key	Action
n	Create new time entry
e	Edit selected entry
d	Delete selected entry
s	Start/stop timer on selected entry

General

Key	Action
?	Toggle help overlay
q / Esc	Quit / go back
Ctrl+C	Force quit

Development

Running Tests

make test

Building Locally

make build

Full Check (Format, Lint, Test)

make check

Disclaimer

Harvest is a registered trademark of Bending Spoons US Inc. This project has no direct affiliation with Harvest or Bending Spoons. It is an independent open source project that integrates with the Harvest API v2.

License

This project is licensed under the MIT License.

About Planet Argon

Oh My Zsh was started by the team at Planet Argon, a Ruby on Rails development consultancy. Check out our other open source projects.