Teamwork CLI

Command line interface for Teamwork

This is useful for repetitive time entry into the Teamwork system: https://www.teamwork.com/time-tracking

Installation

Clearly this depends on nodejs and npm. Get your teamwork credentials then you can either clone the repo to install or use npm.

Credentials

This also depends on your teamwork API key and URL. The url is the base of your teamwork website, for example https://mycompany.teamwork.com. The API key can be found by:

1. Go to Teamwork
2. View your profile
3. Click 'Edit My Profile' button in top right
4. View the 'API & Mobile' tab in the popup.
5. Click 'Show Your Token'

Cloning

git clone https://github.com/jamesburns-rts/teamwork-cli.git
cd teamwork-cli
npm install
node hours.js --url <teamwork base url>
node hours.js --key <teamwork api key>

NPM

sudo npm install -g teamwork-cli
hours --url <teamwork base url>
hours --key <teamwork api key>

Recommendations

To get started run the --interactive (-i) option to navigate through your projects and tasks to get the task IDs you need in a fake directory structure. Use ls to list subdirectory options and cd to move into them (using either the index or id as the argument).

If in interactive mode you can use the search command to find tasks in subdirectories.

I highly suggest navigating to the task you want and then mark it as a favorite like fav mytask you can then use mytask anywhere you would normally use a task ID, such as hours -E mytask to log time. You can also navigate to the task when in interactive move with cd mytask or jump right in with hours -i mytask.

Completions

The zsh tab completion system confuses me but I belive if you copy the zsh-completions file as _hours into any of the directories in $fpath then you should get completions. For example

curl https://raw.githubusercontent.com/jamesburns-rts/teamwork-cli/master/zsh-completions > ~/.oh-my-zsh/completions/_hours
autoload -U compinit # May not be necessary
compinit # May not be necessary

Usage

hours 1.1.17

OPTIONS

	-h, --help 
	Print this help Screen

	-v, --version 
	Print version info

	-i, --interactive [path]
	Enter interactive mode. Optionally add path to start in.

	-l, --time-logged 
	Print time logged

	-p, --tasks 
	Print a list of previous entered tasks for the year

	-q, --entries 
	Print entries of today or date specified

	-Q, --since 
	Print entries since date specified

	-f, --favorites 
	Print the list of your favorites

	-F, --favorites-full 
	Print the list of your favorites and their tasks

	-w, --percentages 
	Print percentages of time logged

	-g, --get 
	Print a peice of data

	-E, --interactive-entry [taskId]
	Enter time through questions for specified task

	-e, --entry 
	Enter time with below options

	-b, --billable [0/1]
	If billable time (default 1)

	-H, --hours [hours]
	Set hours to log (default 0)

	-M, --minutes [minutes]
	Set minutes to log (default 0)

	-d, --date [yyyymmdd]
	Set date to log for (default today)

	-m, --description [message]
	Set description to log (default empty)

	-t, --task [taskId]
	Set the taskId to log to (see --tasks)

	-T, --start-time [HH:MM]
	Set the start time to log (default 09:00)

	-O, --end-time [HH:MM]
	Set the length based on the start/end time (default empty)

	-z, --tags [tag1,tag2,tag3]
	Adds a tag to the time entry. Surround list with quotes if it includes a space

	-c, --move [EntryId]
	Move the time entry to the task specified by --task

	-k, --key [key]
	Set teamwork API key to use in the future

	-u, --url [url]
	Set teamwork URL to use in the future

	-a, --arrived [HH:MM]
	Record the time as when you arrived (default to now)

	-s, --switch [timer]
	Switch to a different timer

	-S, --startstop [timer]
	Start or stop a timer

	-D, --delete-timer [timer]
	Delete a timer

	-A, --add-timer [timer]
	Along with -H and -M adds time to a timer

	-x, --subtract-timer [timer]
	Along with -H and -M subtract from a timer

EXAMPLES

    node hours.js --entry --task 6905921 --start-time "09:00" --hours 1 \
        --minutes 30 --billable 0 --description "Friday Standup"
    Logs an hour and a half for a long Friday standup

    node hours.js -e -t 6905921 -T "09:00" -H 1 -M 30 -b 0 -m "Friday Standup"
    Same as above but using letters instead
        

INTERACTIVE MODE

This mode creates a quasi-terminal with a directory structure setup like teamwork. 
There is a top level "teamwork" directory containing a folder for each project, 
each project contains tasklists, and each tasklist contains tasks.

Once in a task you can log time. You can also create tasks/tasklists.

    EXIT: exit, quit, q, :q, :wq, leave
    Exit interactive mode.

    LIST: list, ls, l, ll
    List the contents of the item - a projects tasklists for example.

    SELECT: select, sel, cd, c, :e, enter, dir
    Select a project, tasklist, or task - aka change directory. You can change to a favorite as well.

    EDIT: edit
    Update a time entry

    MOVE: move, mv
    Move a time entry to another task

    HELP: help, h, pls, halp
    Display this information.

    LOG TIME: log, entry, record
    Log time while in a given task

    CREATE: create, mkdir, touch, make, add
    Create a new item in the entity (new task, tasklist, etc.)

    HOURS: hours, main
    Normal hours command

    PATH: path, pwd
    Display the current path using the Ids.

    ECHO: echo, cat, show, display
    Display the json of the item

    REMOVE: remove, rm, delete, del
    Delete the specified item.

    COPY: copy, cp, duplicate, dup
    Copy the specified item.

    TODAY: today
    Show logged today

    FAVORITE: favorite, fav
    Mark task as favorite: fav [PATH] name

    FAVORITES: favorites, favs, faves, favesies
    List favorites (use -v for task names)

    CLEAR: clear, cle
    Clear screen

    SEARCH: search, /, ?, find
    Searches for a task. If -e option is provided, then time entries with empty descriptions are listed.

    TOTAL: total, time, sum
    Sums the time spent on an item or items

    NOTEBOOKS: notebooks, notes, nb, books
    List the notebooks in the current dir