toggl-fetch makes it easy to periodically retrieve summary reports for a Toggl workspace.
Doing that manually is tedious: Each time you need to generate a new report, you need to remember on what date
the previous report ends -- so that you can let the new report start on the correct date. toggl-fetch takes
care of remembering that piece of information and downloading the report for you.
Contents
The first time you fetch a report for a workspace using toggl-fetch, you need to tell it on what date the report
should start. If you don't specify a start date, then toggl-fetch lets the report start four weeks ago.
Optionally, you can specify the date the report should end (herafter simply called the "end date"). If you don't
specify an end date, toggl-fetch uses today's date.
Being given this information, toggl-fetch downloads the report as a PDF file and stores it on your computer.
It also remembers the "end date" for the report; it does that separately for each workspace, so you can use it for
multiple workspaces.
Now, the next time you use toggl-fetch to fetch a report for the workspace, you can omit the start date.
toggl-fetch then adds one day to the saved "end date" (which it stored the last time you fetched a report)
and uses the result as the new start date for the report. It then remembers the "end date" for the current report so
that it can use that information the next time you use toggl-fetch.
Note
Both the "start date" and the "end date" are treated as inclusive dates; that is, the generated reports will include data for the specified dates.
You can install toggl-fetch using pip:
pip install toggl-fetch
toggl-fetch needs a Toggl API token in order to log in to your Toggl account. You can obtain the API token
for your account at the end of your profile page.
For the following examples, let's assume that you API token is 9fc1632af9abac871694d49727685b90.
Having obtained an API token, you can now generate your first report. To do that, you need to know the name of the workspace you want to generate a report for; let's assume it to be "John Doe's workspace". Also, the report should begin on 2016-01-01 and end on today's date (since the latter is the default, you don't need to specify an end date).
To download the report as a PDF file into your current working directory, execute the following command:
toggl-fetch --api-token 9fc1632af9abac871694d49727685b90 --workspace "John Doe's workspace" --start-date 2016-01-01
That's it. Provided that the API token is valid and a workspace with the specified name exists, you should now
find the report as a PDF file named summary_<end_year>-<end_month>.pdf in the current working directory
(see Specifying an output file template to learn how to change that filename).
Now that you have generated your first report, generating subsequent reports is as easy as running the following command:
toggl-fetch --api-token 9fc1632af9abac871694d49727685b90 --workspace "John Doe's workspace"
Note that we omitted the start date -- this makes toggl-fetch calculate it from the "end date" it stored when you
generated the last report (which in this case, was the first report ever generated).
This again will download the report to a file named summary_<end_year>-<end_month>.pdf in your current
working directory (see also Specifying an output file template).
To view all the command line arguments accepted by toggl-fetch, simply do:
toggl-fetch --help
By default, the report is downloaded into the current working directory as a file named
summary_<end_year>-<end_month>.pdf, where end_year and end_month are taken from
the end date of the report.
This filename template can be changed using the --output option. It takes a relative or absolute filename
as an argument; the special placeholders {start_date} and {end_date} are replaced to produce the name of
the output file.
The default template is summary_{end_date:%Y}-{end_date:%m}.pdf. Here, {end_date} is used twice, but
each of the two placeholders contains a different string after the colon: This is a date format specification
specifying how to format the end date. In this case, the placeholder {end_date:%Y} is replaced by the
year of the end date and the placeholder {end_date:%m} is replaced by the month of the end date.
The Python documentation contains a list of valid date format codes which can be used in the date format
specification. For example, the two {end_date}
placeholders above could be replaced with a single placeholder {end_date:%Y-%m} to produce the same result.
Specifying the workspace name, your API token and maybe even an output file template each time you use toggl-fetch
is annoying. You can avoid having to specify options on the command line by placing them in a configuration file
instead.
toggl-fetch follows the XDG Base Directory Specification. In most cases, this means you can place a configuration
file in ~/.config/toggl-fetch/config.ini and toggl-fetch will find it.
Taking the command line parameters used in A short how-to as an example, a valid configuration file would look like this:
[options]
api_token = 9fc1632af9abac871694d49727685b90
workspace = John Doe's workspaceSpecifying these two options in the configuration file is enough to be able to run toggl-fetch without having to
specify any command line options.
All command line options can be used in the [options] section. Command line parameters without a value
(like --force) can be set by simply using the option name without a value, like this:
[options]
forceWarning
This is only an example. Placing the force option in the configuration file is discouraged for obvious
reasons.
Lines starting with optional whitespace followed by either # or ; are treated as comments and are ignored.
Note
Inline comments (comments at the end of non-empty lines) are not supported.
- Fix: Add forgotten short option
-Vas a counterpart to--version. - Fix: Document return codes for the
main()function. - Fix:
User-Agentheader: Add our version number and correctly format our URL.
- Initial release.