Flow Toggl Plugin

A performant Toggl Track plugin for Flow Launcher to bring time tracking right to your fingertips.

• Features
• Commands
• Demos
• Setup Instructions
• Command Reference
• Licence

Features

• Powerful, speed-optimised interface
• Auto-complete for any time entry started within the last 366 days

  This is significantly longer than the ~1 month of Toggl's own interface!

• Support for projects, clients, and workspaces
• Coloured icons for projects
• Human-friendly date and time display
• Open source
• Private and secure—all data is stored locally!

Commands

• Start new time entries
• Continue a previously tracked time entry
• Stop currently running time entries
• Edit a previously tracked time entry
• Delete a previously tracked time entry
• Reports of tracked time by projects, clients, and entries
• Browser quick-launch shortcut

Demos

tgl

tgl reports

Setup Instructions

1. Install the plugin.

   pm install Toggl Track
   

2. Paste your Toggl Track API key into the plugin settings.

   This can be found at the bottom of your Toggl Track profile settings page.

3. Trigger the plugin with the (configurable) action keyword tgl.

Command Reference

Note

This command reference applies to version v4.1.0.

Older Versions:

• v4.0.0
• v4.0.0-2
• v4.0.0-1
• v4.0.0-0
• v3.0.1
• v3.0.0 (created command reference)

Quick Links

Icon	Link
	tgl
	start
	continue
	stop
	edit
	delete
	reports
	browser
	help
	refresh

---

tgl

Description

📝 The action keyword lists:

1. the result(s) to start a new time entry,
2. past time entries that fuzzy match the current input, and
3. all currently executable plugin commands.

tgl with no further input

When the plugin is triggered with no further input, the list of results will contain:

1. Start an empty time entry now,
2. Start an empty time entry [x time] ago at previous stop time, and
3. A list of currently executable commands.

Note

The previous stop time action is only available if:

1. There is a past time entry, and
2. There is no currently running time entry.

Note

Relevant Usage Tips will also be displayed if Show Usage Results: Tips is enabled in the plugin settings.

tgl [exact partial command name]

When followed by an exact match for the start of any recognised command name, the list of results will contain all the executable commands which fuzzy match the query. This allows you to search for plugin commands without the list of results being flooded by past time entry suggestions.

Note

To create a new time entry that starts with a partial command name, you may escape the partial command with a backslash (\) character.

tgl [command name]

When followed by a full recognised command name, the respective command will be auto-triggered and the list of results will contain its respective actions.

Note

To create a new time entry that starts with a command name, you may escape the command with a backslash (\) character.

tgl ...

When followed by anything other than a command name, the list of results will contain:

1. Start ... now,
2. Start ... [x time] ago at previous stop time,
3. A list of past time entries whose descriptions fuzzy match the ... query, and
4. A list of currently executable commands that fuzzy match the ... query.

Note

The previous stop time action is only available if:

1. There is a past time entry, and
2. There is no currently running time entry.

Note

Relevant Usage Tips will also be displayed if Show Usage Results: Tips is enabled in the plugin settings.

Usage Examples

• tgl
• tgl stop
• tgl edit
• tgl reports

---

tgl start

Description

📝 Start a new time entry.

Note

This command exists at the top-level and does not have a command name (ie no tgl start).

Usage Examples

• tgl
• tgl new time entry
• tgl @[project]
• tgl new time entry@[project]
• tgl Release v1.2.1 -t -10
• tgl New time entry -t 30s @[project]

Symbols, Flags, and Key Modifiers

Name	Symbol	Description	Example
Project Selection Prefix	@	Set a project for the new time entry	@flow-toggl-plugin

Name	Flag	Description	Example
Time Span	-t	Offset the starting time of the new time entry with a specified time span	-t -30 seconds
Clear Description	-C	Empty the time entry description from the Flow search bar	-C

Name	Key Modifier	Description	Example
Quick-Start from Project Selection	Alt	Instantly start the new time entry directly from the project selection screen	tgl Release v4.0.0@flow-toggl > Alt + Enter

Notes and Warnings

Note

1. Any currently running time entry will first be stopped before starting the new time entry to prevent overlapping entries (mimics Toggl Track behaviour)
2. If a time entry is not currently running, there will be an option to start the new time entry at the previous stop time (if one exists).
3. To include a command symbol/flag in your time entry description, you can escape it with a backslash (\), eg tgl Email james\@jamesnzl.xyz \-t -t -5

Important

1. The Time Span flag must be the entered after the time entry description. Anything entered after the -t flag will be ignored.
2. Due to a current Flow Launcher bug, the Alt quick-start will execute if you use the Alt + number hotkey to select a project. This can be circumvented for the time being by changing your Open Result Modifier Key to Ctrl in the Flow Hotkey settings.

Screenshots

---

tgl continue

Description

📝 Continue a previous time entry.

Note

This command exists at the top-level and does not have a command name (ie no tgl continue).

Usage Examples

• tgl [previous time entry description]

Flags

Name	Flag	Description	Example
List Past Time Entries	-l	List all past time entries to continue, even if the query is empty	tgl -l

Key Modifiers

Name	Key Modifier	Description	Example
Quick-Start without editing	Alt	Instantly continue the time entry without confirmation	tgl [past time entry] > Highlight result > Alt + Enter

Notes

Note

1. The default behaviour is to autofill the time entry description/project for start.
2. The list is guaranteed to contain all time entries tracked within the preceeding 12 months.

Screenshots

---

tgl stop

Description

📝 Stop the current time entry.

Usage Examples

• tgl stop
• tgl stop -T -4
• tgl stop -T 1h

Flags

Name	Flag	Description	Example
End Time Span	-T	Offset the stopping time of the current time entry with a specified time span	-T -30 seconds

Notes

Note

1. This command is only available if there is a currently running time entry.
2. Typing the time entry name (or anything else, other than the End Time Span flag) has no effect.

Screenshots

---

tgl edit

Description

📝 Edit a previous time entry.

Usage Examples

• tgl edit [previous time entry description] > tgl edit -C > tgl edit New time entry description
• tgl edit [previous time entry description] > tgl edit -t 20s -T 1h
• tgl edit [previous time entry description] > tgl edit [previous time entry description]@no-project
• tgl edit [previous time entry description] > tgl edit [previous time entry description] -R

Symbols and Flags

Name	Symbol	Description	Example
Project Selection Prefix	@	Edit the project of the selected time entry	@new-project

Name	Flag	Description	Example
Time Span	-t	Offset the starting time of the selected time entry with a specified time span	-t -30 seconds
End Time Span	-T	Offset the stopping time of the selected time entry with a specified time span	-T -30 seconds
Resume Time Entry	-R	Unstop the time entry (ie resume it, ie restart it from the same start time)	-R
Clear Description	-C	Empty the time entry description from the Flow search bar	-C

Notes and Warnings

Note

1. If an End Time Span is specified, the time entry will be stopped (if it is currently running).
2. The End Time Span and Resume Time Entry flags are mutually exclusive (cannot be used together).
3. The Clear Description flag will only empty the time entry description from the Flow search bar, so a replacement can be input quickly.

   To actually clear a time entry's description, use the Clear Description flag then hit the Enter action key to save.

4. tgl edit will use the entered description to perform a fuzzy match against all previously tracked time entries (within the past 12 months), allowing you to quickly apply a previous time entry's description/project/etc.
5. To include a command symbol/flag in your time entry description, you can escape it with a backslash (\), eg tgl edit Email james\@jamesnzl.xyz \-t \-T \-C

Important

1. The Time Span/End Time Span flags must be the entered after the time entry description. Anything entered after the flag(s) will be ignored.
2. The list of editable time entries will only contain up to 1000 of the most-recent time entries due to Toggl limitations.

Screenshots

---

tgl delete

Description

📝 Delete a previous time entry.

Usage Examples

• tgl delete [previous time entry description]

Notes

Note

1. Typing anything on the deletion confirmation page (ie after selecting a time entry) has no effect.

Screenshots

---

tgl reports

Description

📝 View summary and detailed tracked time reports.

Usage Examples

• tgl reports day projects project-one
• tgl reports week clients client-one
• tgl reports month entries [time entry description search query]
• tgl reports week-3 projects no-project [time entry description search query]

With Arbitrary Date(s)

• tgl reports 21/9 entries
• tgl reports 1/1/2021> projects
• tgl reports 2/1/2021>5/6/2021 clients

Flags and Options

Name	Flag	Description	Example
Show Stop Time	-S	Show time entry stop times when displaying a detailed report	-S

Name	Option	Description	Example
Report Span Offset	[span]-[offset]	Offset the report span by a specified offset	month-1
To End Date	[start]>[end]	The separator between the [start] and the [end] of the arbitrary span	21/9>21/10

Notes and Warnings

Note

1. Arbitrary date(s) are parsed according to your system locale (eg for en-US, your format of MM/dd will be used instead).
2. Date parsing is done by the built-in DateTimeOffset.TryParse method. Read about what it supports here and here.
3. Toggl's reports API only supports start/end dates—any time components of the parsed span will be lost and reduced to 00:00:00 for both dates.
4. Using the > separator without supplying an [end] date will produce a span between [start] and the current date.
5. Reports of tracked time entries can be filtered with a fuzzy search.
6. Selecting a time entry will autofill the tgl start command.
7. To include '-S' in your fuzzy search, you can escape it with a backslash—eg tgl reports day entries \-S

Important

1. The [end] date must be after the [start] date.
2. The arbitrary report span must not exceed one year (Toggl API limitation).

Screenshots

With Arbitrary Date(s)

---

tgl browser

Description

📝 Open the Toggl Track website in a browser.

Usage Examples

• tgl browser

---

tgl help

Description

📝 Open plugin command reference.

Usage Examples

• tgl help

Notes

Note

1. This command simply opens this README file to Command Reference.

---

tgl refresh

Description

📝 Refresh plugin cache.

Usage Examples

• tgl refresh

Notes

Note

1. This command should only rarely need to be used, as the cache is automatically cleared after what should be quite sane cache expiration periods.
2. The exception is for any changes made in Toggl Track to the following, as these are cached for up to 3 days:
   1. Project names/colours/clients,
   2. Client names,
   3. Reports time zone, and
   4. First day of the week.

---

Licence

The source code for this plugin is licensed under MIT.