A powerful command-line interface for Harvest time tracking.
- Full Harvest API v2 coverage - Access all Harvest functionality from the command line
- Time tracking - Create, edit, list, and delete time entries with flexible date parsing
- Timer management - Start, stop, restart, and toggle timers with TUI project/task picker
- Weekly dashboard - Visual summary of your time tracking week
- Financial management - Expenses with receipt uploads, invoices with full workflow, estimates
- Resource management - Projects, clients, tasks, and users
- Reports - Time, expense, uninvoiced, and budget reports with rate limit awareness
- Approval workflows - Submit, approve, and reject time entries
- Bulk operations - CSV import/export for time entries
- External references - Link time entries to JIRA, Asana, GitHub, and other tools
- TUI interactive pickers - Fuzzy-search project and task selection
- Multi-account support - Manage multiple Harvest accounts with aliases
- Secure credential storage - System keyring integration (macOS Keychain, Linux Secret Service, Windows Credential Manager)
- Multiple output formats - Table, JSON, or TSV for scripting
brew install dedene/tap/harvestcligo install github.com/dedene/harvest-cli/cmd/harvest@latestDownload pre-built binaries from the Releases page.
Register an OAuth application in your Harvest Developer Settings, then:
harvest auth setup <client_id> <client_secret>harvest auth loginThis opens your browser for OAuth authorization. For headless environments, use --manual mode.
Alternatively, use a Personal Access Token:
harvest auth login --pat# Start a timer (interactive project/task picker)
harvest timer start
# Log time directly
harvest time add -p "My Project" --task "Development" -h 2 -n "Worked on feature X"
# View your dashboard
harvest dashboard
# Stop running timer
harvest timer stop| Command | Description |
|---|---|
auth |
Authentication: login, logout, status, list, switch accounts |
config |
Configuration: show, set, unset, path |
time |
Time entries: list, show, add, edit, remove, log |
timer |
Timer control: status, start, stop, restart, toggle |
dashboard |
Weekly time tracking summary |
projects |
Projects: list, show, add, edit, remove |
clients |
Clients: list, show, add, edit, remove |
tasks |
Tasks: list, show, add, edit, remove |
users |
Users: list, show, me, add, edit, remove |
expenses |
Expenses: list, show, add, edit, remove (with receipt upload) |
invoices |
Invoices: list, show, add, edit, remove, send, mark-sent/closed/draft, payments |
estimates |
Estimates: list, show, add, edit, remove, send, mark-sent/accepted/declined |
reports |
Reports: time, expenses, uninvoiced, budget |
approvals |
Approvals: pending, submit, approve, reject |
bulk |
Bulk operations: export, import (CSV) |
company |
Show company information |
completion |
Generate shell completions (bash, zsh, fish) |
version |
Show version information |
Configuration is stored in ~/.config/harvest/ (or $XDG_CONFIG_HOME/harvest/).
# View current config
harvest config show
# Set default account
harvest config set default_account [email protected]
# Set timezone
harvest config set default_timezone America/New_York
# Create account alias
harvest config set alias.work [email protected]| Variable | Description |
|---|---|
HARVESTCLI_ACCOUNT |
Default account email or alias |
HARVESTCLI_ACCOUNT_ID |
Harvest account ID override |
| Flag | Description |
|---|---|
-a, --account |
Account email or alias |
--account-id |
Harvest account ID override |
-j, --json |
Output as JSON |
--plain |
Output as TSV (plain text) |
-v, --verbose |
Verbose output |
--color |
Color output: auto, always, never |
OAuth provides secure, token-based authentication with automatic refresh:
# Setup OAuth client (one-time)
harvest auth setup <client_id> <client_secret>
# Login (opens browser)
harvest auth login
# Login in headless/SSH environment
harvest auth login --manualFor simpler setups or CI/CD, use a PAT from Harvest Developer Settings:
harvest auth login --pat# List all authenticated accounts
harvest auth list
# Switch default account
harvest auth switch [email protected]
# Use specific account for a command
harvest -a [email protected] time list
# Create an alias
harvest config set alias.personal [email protected]
harvest -a personal dashboard# List today's entries
harvest time list -f today
# List this week's entries for a project
harvest time list -f "monday" -t "today" -p "Client Project"
# Quick time log with wizard
harvest time log
# Add time with external reference (JIRA)
harvest time add -p "Project" --task "Dev" -h 2 --external-ref-id "JIRA-123" --external-ref-service jira# Start timer (interactive picker)
harvest timer start
# Start timer for specific project/task
harvest timer start -p "My Project" --task "Meetings"
# Toggle (stop if running, restart last if not)
harvest timer toggle
# Check status
harvest timer# Time report by project
harvest reports time -f "2024-01-01" -t "2024-01-31" --by projects
# Expense report by category
harvest reports expenses -f "2024-01-01" -t "2024-01-31" --by categories
# Uninvoiced amounts
harvest reports uninvoiced -f "2024-01-01" -t "2024-01-31"
# Project budgets
harvest reports budget --active# Export time entries to CSV
harvest bulk export -f "2024-01-01" -t "2024-01-31" -o timesheet.csv
# Import time entries from CSV
harvest bulk import timesheet.csv
# Dry run (preview without creating)
harvest bulk import timesheet.csv --dry-run# Create invoice
harvest invoices add -c "Client Name" --subject "January 2024"
# Send invoice
harvest invoices send 12345 -r "[email protected]"
# Record payment
harvest invoices payments add 12345 --amount 1500.00# Bash
harvest completion bash > /etc/bash_completion.d/harvest
# Zsh
harvest completion zsh > "${fpath[1]}/_harvest"
# Fish
harvest completion fish > ~/.config/fish/completions/harvest.fishMIT License - see LICENSE for details.