A simple command-line utility for logging time entries directly from your terminal to your Harvest account. This tool helps developers and teams track their time efficiently without leaving the command line.
- âś… Create, update, delete, and list time entries directly from your terminal
- âś… Interactive prompts with smart defaults for quick time logging
- âś… Project and task selection from your Harvest account configuration
- âś… Daily, weekly, and monthly time summaries with task-based aggregation
- âś… Multiple time entry selection for batch operations
- âś… Tabular output format for better readability
- âś… Date filtering for all commands
- âś… Default interactive mode for better user experience
- âś… Configuration inspection for easy troubleshooting
- Go 1.18 or higher
- A Harvest account with API access
We provide installation scripts for easy setup:
macOS/Linux:
# Clone the repository
git clone https://github.com/amanangira/harvest-cli-utility.git
# Navigate to the project directory
cd harvest-cli-utility
# Run the installation script
chmod +x install.sh
./install.sh
Windows:
# Clone the repository
git clone https://github.com/amanangira/harvest-cli-utility.git
# Navigate to the project directory
cd harvest-cli-utility
# Run the installation script (Command Prompt)
install.bat
# Or if using Git Bash
chmod +x install.sh
./install.sh
The installation scripts will:
- Check if Go is installed with the right version
- Build the project
- Install the binary to your PATH
- Create a global config file at
~/.harvest-config.json
(or%USERPROFILE%\.harvest-config.json
on Windows) - Create a local config.json in the current directory (for project-specific settings)
- Provide instructions for configuration
If you prefer to install manually:
# Clone the repository
git clone https://github.com/amanangira/harvest-cli-utility.git
# Navigate to the project directory
cd harvest-cli-utility
# Build the project
go build -o h
# Move the binary to a directory in your PATH (optional)
# For macOS/Linux:
mv h /usr/local/bin/
# For Windows (in PowerShell, run as Administrator):
# Copy-Item -Path .\h.exe -Destination "$env:USERPROFILE\bin\h.exe"
# Create a global config file
# For macOS/Linux:
cat > ~/.harvest-config.json << EOF
{
"projects": [],
"default_project": "",
"default_task": "",
"year_start_date": "01-01",
"monthly_capacity_hours": 160,
"billable_task_ids": [],
"harvest_api": {
"account_id": "YOUR_HARVEST_ACCOUNT_ID",
"token": "YOUR_HARVEST_API_TOKEN"
}
}
EOF
# For Windows (in PowerShell):
# Set-Content -Path "$env:USERPROFILE\.harvest-config.json" -Value "{`"projects`":[],`"default_project`":`"`",`"default_task`":`"`",`"year_start_date`":`"01-01`",`"monthly_capacity_hours`":160,`"billable_task_ids`":[],`"harvest_api`":{`"account_id`":`"YOUR_HARVEST_ACCOUNT_ID`",`"token`":`"YOUR_HARVEST_API_TOKEN`"}}"
The application looks for configuration in the following locations (in order):
config.json
in the current directory (for project-specific settings)- In the same directory as the executable
~/.harvest-config.json
(or%USERPROFILE%\.harvest-config.json
on Windows) for global settings- In the parent directory
Create or edit your configuration file with your Harvest API credentials and project information:
{
"projects": [
{
"id": 123,
"name": "Project A",
"tasks": [
{
"id": 456,
"name": "Software Development"
},
{
"id": 678,
"name": "Non-Billable"
}
]
}
],
"default_project": "Project A",
"default_task": "Software Development",
"year_start_date": "01-01",
"monthly_capacity_hours": 160,
"billable_task_ids": [456],
"harvest_api": {
"account_id": "YOUR_HARVEST_ACCOUNT_ID",
"token": "YOUR_HARVEST_API_TOKEN"
}
}
- Log in to your Harvest account
- Go to Settings > Developer
- Create a new personal access token
- Note your Account ID and Token
The CLI utility uses a simple syntax:
h [command] [arguments]
# Quick create with defaults
h create -D
# Interactive create (prompts for all fields)
h create
# Create with specific values
h create -d 2023-03-06 -p "Project A" -a "Software Development" -t "7:30"
Flags:
-d, --date string
: Date in YYYY-MM-DD format (default: today)-p, --project string
: Project name (must match a name in config.json)-a, --action string
: Action/Task name (must match a task name for the selected project)-t, --duration string
: Duration in HH:MM format (e.g., "7:30" for 7 hours and 30 minutes)-D, --default-mode
: Use default project and task from config
# Delete entries interactively (select multiple)
h delete
# Delete entries for a specific date
h delete -d 2023-03-06
# Delete a specific entry by ID
h delete 123456789 -n
Flags:
-n, --non-interactive
: Use non-interactive mode with a time entry ID-d, --date string
: Date in YYYY-MM-DD format (default: today)
Multi-Selection Interface:
The delete command features an intuitive multi-selection interface that allows you to:
- Select/deselect individual entries by entering their number
- Select all entries at once with 'a'
- Deselect all entries with 'n'
- Proceed with deletion with 'd'
- Cancel the operation with 'q'
This makes it easy to delete multiple time entries in a single operation.
# Update an entry (select from today's entries)
h update
# Update an entry from a specific date
h update -d 2023-03-06
Flags:
-d, --date string
: Date in YYYY-MM-DD format (default: today)
# List today's entries
h list
# List entries for a specific date
h list -d 2023-03-06
# Show weekly summary
h list -w
# Show monthly summary
h list -m
# Show yearly summary
h list -y
Flags:
-d, --date string
: Date in YYYY-MM-DD format (default: today)-m, --monthly
: Show monthly summary-w, --weekly
: Show weekly summary-y, --yearly
: Show yearly summary (based on year_start_date in config)
Enhanced Output:
The list command now provides detailed task-based aggregation for all views:
- Daily view: Shows individual time entries followed by a task summary with percentages
- Weekly view: Shows project/task breakdown followed by a task-only summary across all projects
- Monthly view: Shows capacity utilization metrics, billable vs. non-billable hours, project/task breakdown with billable status, and a task-only summary across all projects
- Yearly view: Shows capacity utilization metrics, billable vs. non-billable hours, project/task breakdown with billable status, and a task-only summary across all projects for the entire year
The yearly view respects the year_start_date
configuration option (format: "MM-DD") which lets you define when your year starts. If not specified, it defaults to January 1st (01-01).
Monthly and yearly views now include capacity utilization metrics based on the monthly_capacity_hours
setting (defaults to 160 hours) and billable hours calculated using the billable_task_ids
list in your configuration.
# Display configuration file path and contents (sensitive data masked)
h config
# Display configuration with sensitive information visible
h config -s
Flags:
-s, --show-sensitive
: Show sensitive information like API tokens
# Quick logging with defaults
h create -D
# Interactive logging
h create
# List today's entries
h list
# Update an entry if needed
h update
# View weekly summary
h list -w
# Delete incorrect entries
h delete
# Select the date containing entries to delete
h delete -d 2023-03-06
# Use the multi-select interface:
# - Enter numbers to select/deselect entries
# - Enter 'a' to select all
# - Enter 'd' when done
# View task distribution for today
h list
# View task distribution for the week
h list -w
# View task distribution for the month
h list -m
# View task distribution for the entire year
h list -y
# View which configuration file is being used and its contents
h config
# Troubleshoot API connection issues by viewing sensitive data
h config -s
# View monthly utilization metrics
h list -m
# View yearly utilization metrics
h list -y
In both monthly and yearly views, you'll see:
- Capacity threshold (based on monthly_capacity_hours setting)
- Total hours worked and percentage of capacity
- Billable vs. non-billable hours breakdown
- Per-task utilization with billable status
- API Authentication Errors: Ensure your Harvest API credentials are correct in your config file
- Project/Task Not Found: Verify that project and task names match exactly with your configuration
- Command Not Found: Make sure the binary is in your PATH or use the full path to the executable
- Config Not Found: Check that you have a valid config file in one of the supported locations
For each command, you can use the --help
flag to see available options:
h --help
h create --help
h delete --help
h update --help
h list --help
h config --help
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.