A performant Toggl Track plugin for Flow Launcher to bring time tracking right to your fingertips.
- 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!
Startnew time entriesContinuea previously tracked time entryStopcurrently running time entriesEdita previously tracked time entryDeletea previously tracked time entryReportsof tracked time by projects, clients, and entriesBrowserquick-launch shortcut
-
Install the plugin.
pm install Toggl Track -
Paste your Toggl Track API key into the plugin settings.
This can be found at the bottom of your Toggl Track profile settings page.
-
Trigger the plugin with the (configurable) action keyword
tgl.
Note
This command reference applies to version v4.1.0.
Older Versions:
| Icon | Link |
|---|---|
 |
tgl |
|
start |
|
continue |
|
stop |
|
edit |
|
delete |
|
reports |
 |
browser |
 |
help |
 |
refresh |
đź“ť The action keyword lists:
- the result(s) to start a new time entry,
- past time entries that fuzzy match the current input, and
- all currently executable plugin commands.
When the plugin is triggered with no further input, the list of results will contain:
Start an empty time entry now,Start an empty time entry [x time] ago at previous stop time, and- A list of currently executable commands.
Note
The previous stop time action is only available if:
- There is a past time entry, and
- 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.
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.
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.
When followed by anything other than a command name, the list of results will contain:
Start ... now,Start ... [x time] ago at previous stop time,- A list of past time entries whose descriptions fuzzy match the
...query, and - A list of currently executable commands that fuzzy match the
...query.
Note
The previous stop time action is only available if:
- There is a past time entry, and
- 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.
tgltgl stoptgl edittgl reports
đź“ť Start a new time entry.
Note
This command exists at the top-level and does not have a command name (ie no tgl start).
tgltgl new time entrytgl @[project]tgl new time entry@[project]tgl Release v1.2.1 -t -10tgl New time entry -t 30s @[project]
| 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 |
Note
- Any currently running time entry will first be stopped before starting the new time entry to prevent overlapping entries (mimics Toggl Track behaviour)
- 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).
- To include a command symbol/flag in your time entry description, you can escape it with a backslash (
\), egtgl Email james\@jamesnzl.xyz \-t -t -5
Important
- The
Time Spanflag must be the entered after the time entry description. Anything entered after the-tflag will be ignored. - Due to a current Flow Launcher bug, the
Altquick-start will execute if you use theAlt+numberhotkey to select a project. This can be circumvented for the time being by changing yourOpen Result Modifier KeytoCtrlin the FlowHotkeysettings.
đź“ť Continue a previous time entry.
Note
This command exists at the top-level and does not have a command name (ie no tgl continue).
tgl [previous time entry description]
| Name | Flag | Description | Example |
|---|---|---|---|
| List Past Time Entries | -l |
List all past time entries to continue, even if the query is empty | tgl -l |
| 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 |
Note
- The default behaviour is to autofill the time entry description/project for
start. - The list is guaranteed to contain all time entries tracked within the preceeding 12 months.
đź“ť Stop the current time entry.
tgl stoptgl stop -T -4tgl stop -T 1h
| 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 |
Note
- This command is only available if there is a currently running time entry.
- Typing the time entry name (or anything else, other than the
End Time Spanflag) has no effect.
đź“ť Edit a previous time entry.
tgl edit [previous time entry description]>tgl edit -C>tgl edit New time entry descriptiontgl edit [previous time entry description]>tgl edit -t 20s -T 1htgl edit [previous time entry description]>tgl edit [previous time entry description]@no-projecttgl edit [previous time entry description]>tgl edit [previous time entry description] -R
| 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 |
Note
- If an
End Time Spanis specified, the time entry will be stopped (if it is currently running). - The
End Time SpanandResume Time Entryflags are mutually exclusive (cannot be used together). - The
Clear Descriptionflag 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 Descriptionflag then hit theEnteraction key to save. tgl editwill 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.- To include a command symbol/flag in your time entry description, you can escape it with a backslash (
\), egtgl edit Email james\@jamesnzl.xyz \-t \-T \-C
Important
- The
Time Span/End Time Spanflags must be the entered after the time entry description. Anything entered after the flag(s) will be ignored. - The list of editable time entries will only contain up to
1000of the most-recent time entries due to Toggl limitations.
đź“ť Delete a previous time entry.
tgl delete [previous time entry description]
Note
- Typing anything on the deletion confirmation page (ie after selecting a time entry) has no effect.
đź“ť View summary and detailed tracked time reports.
tgl reports day projects project-onetgl reports week clients client-onetgl reports month entries [time entry description search query]tgl reports week-3 projects no-project [time entry description search query]
tgl reports 21/9 entriestgl reports 1/1/2021> projectstgl reports 2/1/2021>5/6/2021 clients
| 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 |
Note
- Arbitrary date(s) are parsed according to your system locale (eg for
en-US, your format ofMM/ddwill be used instead). - Date parsing is done by the built-in
DateTimeOffset.TryParsemethod. Read about what it supports here and here. - Toggl's reports API only supports start/end dates—any time components of the parsed span will be lost and reduced to
00:00:00for both dates. - Using the
>separator without supplying an[end]date will produce a span between[start]and the current date. - Reports of tracked time entries can be filtered with a fuzzy search.
- Selecting a time entry will autofill the
tgl startcommand. - To include
'-S'in your fuzzy search, you can escape it with a backslash—egtgl reports day entries \-S
Important
- The
[end]date must be after the[start]date. - The arbitrary report span must not exceed one year (Toggl API limitation).
đź“ť Open the Toggl Track website in a browser.
tgl browser
đź“ť Open plugin command reference.
tgl help
Note
- This command simply opens this
READMEfile to Command Reference.
đź“ť Refresh plugin cache.
tgl refresh
Note
- This command should only rarely need to be used, as the cache is automatically cleared after what should be quite sane cache expiration periods.
- The exception is for any changes made in Toggl Track to the following, as these are cached for up to
3days:- Project names/colours/clients,
- Client names,
- Reports time zone, and
- First day of the week.
The source code for this plugin is licensed under MIT.