/flow-toggl-plugin

A powerful, ergonomic Flow Launcher plugin for quick-fire time tracking with Toggl Track.

Primary LanguageC#MIT LicenseMIT




GitHub issues GitHub pull requests GitHub workflow status GitHub last commit

Flow Toggl Plugin

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

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

Plugin demo

tgl reports

View tracked time 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:

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 with no input

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.

tgl with a partial command name and fuzzy results

tgl with a partial command name

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 with an escaped partial command name

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.

tgl with a command name

Note

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

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.

tgl with a fuzzy query

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

Project selection

Creating a new time entry

Selecting a project for new time entry

Creating a new time entry with a selected project

Creating a new time entry in the past

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

Selecting a previous time entry to continue

Selected a previous time entry to continue

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

Stopping the running time entry in the future

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

Selecting a time entry to edit

Fuzzy query of other time entries to which to match

Selecting a new project for the time entry

Selected a new project for the time entry

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

Deleting running time entry

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

Tracked time report span selection

View tracked time report from yesterday

Tracked time report grouping options

View tracked time report by project

View tracked time report by project entries

View detailed tracked time report by project entries

View detailed tracked time report by project entries with stop time

View tracked time report by client

View tracked time report by client projects

View tracked time report by entries with fuzzy filter

With Arbitrary Date(s)

View tracked time report on an arbitrary date

View tracked time report from an arbitrary date to now

View tracked time report over an arbitrary span

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.