Clijsters/PSToggl

Interact with the Toggl API through PowerShell

PSToggl

A fully featured Toggl client for your PowerShell - based on Toggl's API v8

---

Features

PSToggl perfectly integrates in your existing PowerShell environment, independent of the operating system you want to work with. It makes heavy use of PowerShells pipeline abilities and integrates with other modules like PSJiraJiraPS, PSExcel, PSHipchat and so on. It helps you to increase your productivity by providing extended reporting features, migration&sync features (e.g. Toggl -> JIRA work logs) and a robust interactive PowerShell client.

As you might already know from git (posh-git) PSToggl shows information like the current timer / project at your PowerShell prompt, extends auto completion, provides aliases and templates, and much more.

Contents

1. Features
2. Contents
3. Getting started
   • Installation
   • Configuration
4. How to use
5. License

Getting started

Installation

It's recommended to use Install-Module to install PSToggl:

#Running PowerShell as Administrator - Install globally
Install-Module PSToggl

#Without Administrator privileges - Only for the current user
Install-Module PSToggl -Scope CurrentUser

Alternatively, just clone this repo and import PSToggl:

git clone https://github.com/clijsters/PSToggl
Import-Module PSToggl/PSToggl/PSToggl/PSToggl.psm1 # Yeah, 4 times

Configuration

To set your Personal Access Token and your default workspace (yeah I know), create a ~/.PSToggl JSON File with the following content:

{
    "APIKey": "ffffffffffffffffffffffffffffffff",
    "Workspace": 1234567
}

In future releases, this cmdlet will use its own config store and securestrings.

How to use

The best way to become familiar with PSToggl is to use Get-Help

PS> Get-Help about_PSToggl
PS> Get-Help Start-TogglEntry
PS> # And so on

Start a new Timer

PS> Start-TogglEntry "Getting started with PSToggl"

Change the currently running Timer

PS> Get-TogglEntry -Current | Add-TogglTag "educational"

Get all Time Entries for a specified Project, which are not billed and tag them

PS> Get-TogglProject "homepage" | Get-TogglEntry | Where-Object {-not $_.billed} | Add-TogglTag "overdue"

Use the output of Measure-Command to create a new Entry

PS> Measure-Command {mvn -U compile} | New-TogglEntry "Wasting time with coffee..."

PS> Measure-Command {git commit} | New-TogglEntry "Writing well formatted, meaningful git commit messages" -Tags @("efficiency", "Drumherum")

---

Beta Features & special use cases

If you have tasks, repeating with the same configuration (Tags, project, title), you probably don't want to type the whole timer properties every time.
For this case, we use templates. Where the Toggl Desktop client suggests timer configurations based on your previous runned timers, PSToggl introduces templates.

Theses templates - once configured - give you the ability to quickly start a timer with a defined name, project, client, tags, ...

There are two types of templates. Full templates and configuration templates. The latter is without a title.

Tab completion based on previous entered information will also be supported to mimic the behavior of Toggl Desktop. (And because it makes it much much faster to use Cmdlets)

PS> Start-TogglEntry -Template vcs
PS> git checkout master
PS> git merge dev --no-ff --no-commit
PS> vim pom.xml
PS> #[...]
PS> git add pom.xml
PS> git commit -m "Merge dev branch and increase version number"
PS> git push fork dev
PS> Invoke-Chrome -bookmark GitLab
PS> Stop-TogglEntry -PassThrough | Select Minutes
PS> #Stop-TogglEntry -PassThrough | New-JiraWorklog -Issue Proj-12

Test Coverage

Current

Historical