grunt-toggl
v1.0.0
Published
Toggl API for Grunt. E.g. start time tracking with `grunt watch` or `grunt toggl`
Downloads
7
Maintainers
Readme
grunt-toggl
Toggl API for Grunt. E.g. start time tracking with
grunt watch
orgrunt toggl
Demo
Getting Started
This plugin requires Grunt >=0.4.4
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-toggl --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-toggl');
The "toggl" task
Overview
In your project's Gruntfile, add a section named toggl
to the data object
passed into grunt.initConfig()
.
grunt.initConfig({
toggl: {
options: {
apiKey: '',
settingsFile: 'toggl.json'
workspace: null,
project: null,
data: {
description: '<%= pkg.name %>',
}
}
},
});
Options
Your Toggl API key is required for this task. Get it from your profile on Toggl.com https://www.toggl.com/app/#profile.
Here are the ways to specify your API key:
options.apiKey
Type: String
Default value: ``
This is one way to specify your Toggl API key. Not secure if your repo is public.
options.apiEnvVar
Type: String
Default value: ``
This is one way to specify your Toggl API key. Safe but you'll have to configure the shell env var on the machine you're using the task on.
options.settingsFile
Type: String
Default value: .toggl
This is another way to specify your Toggl API Key. Enter a filename to a JSON file that contains the key "apiKey" and value with your Toggl API key.
{
"apiKey": "demokeydemokeydemokey",
"workspace": 12345
"project": 1111111
}
You can also specify the workspace here.
This format is useful if you keep your Gruntfile in version control and don't
want your API key in it (e.g. add your .toggl
file to your .gitignore
).
Other options
options.workspace
Type: Integer
Default value: null
OPTIONAL (if specified in settingsFile). Equivalent to options.data.wid
.
Specify the Toggl Workspace ID that newly created time entries should go into.
options.project
Type: Integer
Default value: null
OPTIONAL. Equivalent to options.data.pid
. Specify the Toggl Project ID that
newly created time entries should go into.
options.data
Type: Object
Default value: {}
The data
object can take any values from the toggl time_entries
API
endpoint:
description: (string, strongly suggested to be used)
I like to use the
package.json
name in the description, assuming you have it loaded into the pkg variable (pkg: grunt.file.readJSON('package.json')
):data: { description: '<%= pkg.name %>' }
wid: workspace ID (integer, required if pid or tid not supplied).
- See Finding your workspace IDs for how to get the ID using this grunt task.
pid: project ID (integer, not required)
- See Finding your project IDs for how to get the ID using this grunt task.
tid: task ID (integer, not required)
billable: (boolean, not required, default false, available for pro workspaces)
start: time entry start time (string, required, ISO 8601 date and time)
stop: time entry stop time (string, not required, ISO 8601 date and time)
duration: time entry duration in seconds. If the time entry is currently running, the duration attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch. (integer, required)
created_with: the name of your client app (string, required)
tags: a list of tag names (array of strings, not required)
duronly: should Toggl show the start and stop time of this time entry? (boolean, not required)
at: timestamp that is sent in the response, indicates the time item was last updated
See this doc for the latest properties available for the API: https://github.com/toggl/toggl_api_docs/blob/master/chapters/time_entries.md
Data in this object will override the workspace
and project
properties for
data.wid
and data.pid
Usage Examples
Finding your workspace IDs
Use:
grunt toggl:MYTASK:workspaces
To get a JSON list of workspaces. MYTASK
should be whatever task you have
configured, since you still need a valid API Key to get the workspaces.
OR just run the task without a workspace set. It will list your workspaces by default.
Finding your project IDs
Use:
grunt toggl:MYTASK:projects
To get a JSON list of projects in the configured workspace. Your task needs to
have a Workspace ID properly setup in order to use this argument (valid
workspace
or wid
set in the options).
Stop the current task
Use:
grunt toggl:MYTASK:stopCurrent
To stop the current task timer. This will call the API to find out if there is a current timer running. If there is, another call is made to stop it.
OR add this to your Gruntfile.js
grunt.registerTask('toggl:stop', ['toggl:default:stopCurrent']);
and you will be able to simply call
grunt toggl:stop
Default Options
grunt.initConfig({
toggl: {
options: {
settingsFile: '.toggl',
workspace: null,
}
},
});
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
TODO
debug
option that deletes time entries as soon as they're created.
Release History
- 2015-02-22 v1.0.0 [CHANGED] dependency bump
- 2015-02-21 v0.3.0 [CHANGED] support grunt >=0.4.4 in package.json
- 2014-04-29 v0.2.0 [ADDED] argument for listing projects in a workspace
- 2014-04-29 v0.2.0 [ADDED] argument for listing projects in a workspace
[CHANGED] arg for listing workspaces
- 2014-04-28 v0.1.1 Alpha READY. It works.
- 2014-04-28 v0.1.0 Work in progress, not ready.