Harvest Command Line
HCl is a command-line tool for interacting with Harvest time sheets using the Harvest time tracking API.
You can install hcl directly from rubygems.org:
gem install hcl
or you can install from source:
rake doc && rake install
Once installed, you can view this README as a man page:
gem man hcl
I recommend aliasing your
man command to additionally load gem man pages:
alias man="gem man -ls"
hcl [start] @<task_alias> [+<time>] [<message>] hcl note <message> hcl stop [<message>] hcl resume [@<task_alias>] hcl log @<task_alias> [+<time>] [<message>] hcl show [<date>] hcl tasks [<project_code>] hcl alias <task_alias> <project_id> <task_id> hcl unalias <task_alias> hcl aliases hcl (cancel | nvm | oops) hcl config hcl status
Available Projects and Tasks
To start a new timer you need to identify the project and task. The tasks command displays a list of available tasks with their project and task IDs.
You can also pass a project code (this is the short optional code associated with each project) to list only the tasks for that project.
Starting a Timer
Since it's not practical to enter two long numbers every time you want to identify a task, HCl supports task aliases:
hcl alias tacodev 1234 5678 hcl @tacodev Adding a new feature
Starting a Timer with Initial Time
You can also provide an initial time when starting a new timer. This can be expressed in floating-point or HH:MM. The following two commands are equivalent:
hcl @tacodev +0:15 Doing some stuff hcl +.25 @tacodev Doing some stuff
Getting the Current Status
The show command can give you a live view of your current day including any running tasks, last note, and total time.
Show can also be used with a variety of date formats. See Date Formats for more information
Adding Notes to a Running Task
While a task is running you can append lines to the task notes:
hcl note Then I did something else
show only displays the last line of the timer notes.
You can list all the notes for a running timer by issuing the note
command without any arguments:
Stopping a Timer
The following command will stop a running timer (currently only one timer at a time is supported). You can provide a message when stopping a timer as well:
hcl stop All done doing things
Toggling a Timer
Toggle the most recently stopped or running timer. Specify a task to toggle the last timer for that specific task:
hcl toggle hcl toggle @xdev
Canceling a Timer
If you accidentally started a timer that you didn't mean to, you can cancel it:
This will delete the running timer, or the last-updated timer if one isn't
running. You can also use
oops instead of
Logging without Starting a Timer
You can log time and notes without leaving a timer running. It takes the same arguments as start:
hcl log @xdev +1 Worked for an hour.
The above starts and immediately stops a one-hour timer with the given note.
Bash Tab Completions
You can enable auto-completion of commands, project ids, task ids and task aliases by adding this to your shell configuration:
source $(ruby -e "print File.dirname(Gem.bin_path('hcl', 'hcl'))")/_hcl_completions
You can modify your credentials with the
--reauth option, and review them
hcl config. If you'd rather store multiple configurations at
once, specify an alternate configuration directory in the environment as
HCL_DIR. This can be used to interact with multiple harvest accounts at
Here is a shell alias
myhcl with a separate configuration from the
hcl command, and another command to configure alias completion:
alias myhcl="env HCL_DIR=~/.myhcl hcl" complete -F _hcl myhcl
Adding something like the above to your bashrc will enable a new command,
myhcl. When using
myhcl you can use different credentials and aliases,
hcl will continue to function with your original configuration.
An interactive Ruby console is provided to allow you to use the fairly
powerful Harvest API client built into HCl, since not all of its
features are exposed via the command line. The current
It's also possible to issue HCl commands directly (except
below), or to query specific JSON end points and have the results
hcl console hcl> show "yesterday" # => prints yesterday's timesheet, note the quotes! hcl> hcl.http.get('daily') # => displays a pretty-printed version of the JSON output
Note that the HCl internals may change without notice.
Also, commands (like
alias) that are also reserved words in Ruby
can't be issued directly (use
send :alias instead).
Dates can be expressed in a variety of ways. See the Chronic documentation for more information about available date input formats. The following commands show the time sheet for the specified day:
hcl show yesterday hcl show last friday hcl show 2 days ago hcl show 1 week ago
Harvest service status
Harvest provides a status API, which you can query using the
hcl status command. This will tell you whether Harvest itself is up,
along with a timestamp of when it was last tested.
HCl was designed and implemented by Zack Hobson.
See LICENSE for copyright details.