# clockify-tool
The Clockify Tool (`cft`) can be used to list, create, and delete time entries
in Clockify.
With `cft` you can make use of time entry "templates" (see `Advanced
configuration`) to rapidly create time entries. For example if you regularly
have a 15 minute scrum meeting you could create a "scrum" time entry template
that allows you to add a time entry like this:
./cft +scrum
## Installation
Install via PyPi:
pip install clockifytool
...Or clone this repo, change into the repo directory, then enter the following
command:
pip install -r requirements/base.txt
## Basic Configuration
To use `cft` you'll need to, in the Clockify web UI, click the "GENERATE"
button on the "Personal settings" page to generate an API key. You'll then need
to put the key into the `cft` configuration file, which is YAML-formatted and
must be created in `$HOME/.cft.yml`.
Here's an example configuration file containing an API key:
api key: aLedJtL4rl48s2O7
Once you've created a configuration file, you can then run `cft` which will
provide you will a list of available workspaces.
For example:
$ ./cft
Please set workspace ID as "workspace" in /home/vagrant/.cft.yml.
Available workspaces:
* Client-Project-Task Workspace [4c31a29da059321c02e301e0]
Edit the configuration file to set the ID of the workspace you'd like to use.
Example configuration with API key and workspace set:
api key: aLedJtL4rl48s2O7
workspace: 4c31a29da059321c02e301e0
Read on to learn about the basic functionality of `cft` and, once you've got
the hang of things, check out `Advanced Configuration` to learn how you can
save time when entering new time entries.
## Commands
Clockify Tool allows you to list, create and delete Clockify time entries. You
can also list projects, project tasks, and workspaces to find out their IDs.
### Listing time entries in a period of time
Help for the list command:
$ ./cft list -h
usage: cft list [-h] [-s start date] [-e end date] [--strict] [-v] [period]
positional arguments:
period time period: optional, overrides -s and -e
optional arguments:
-h, --help show this help message and exit
-s start date, --start start date
-e end date, --end end date
--strict
-v, --verbose
Available periods: "yesterday" ("y"): day before today, "daybeforeyesterday"
("dby"): day before yesterday, "lastweek" ("lw"): last work week (Monday to
Friday), "currentweek" ("cw"): current work week (Monday to Friday),
"fulllastweek" ("flw"): last full week (Sunday to Saturday), "fullcurrentweek"
("fcw"): current full week (Sunday to Saturday), "lastmonth" ("lm"): last
month, "currentmonth" ("cm"): current month, "lastyear" ("ly"): last year,
"currentyear" ("cy"): current year, "monday" ("mon"): Monday, "tuesday"
("tue"): Tuesday, "wednesday" ("wed"): Wednesday, "thursday" ("thu"):
Thursday, "friday" ("fri"): Friday, "saturday" ("sat"): Saturday, "sunday"
("sun"): Sunday, "lastmonday" ("lmon"): Last Monday, "lasttuesday" ("ltue"):
Last Tuesday, "lastwednesday" ("lwed"): Last Wednesday, "lastthursday"
("lthu"): Last Thursday, "lastfriday" ("lfri"): Last Friday, "lastsaturday"
("lsat"): Last Saturday, "lastsunday" ("lsun"): Last Sunday,
"currentpayperiod" ("cp"): current pay period, "previouspayperiod" ("pp"):
previous pay period
Example list of today's time entries:
./cft
Here's example output:
$ ./cft
Fetching time entries from 2020-02-13 (Thursday)...
Time entries:
* Reading email. (Email: 5cdb08621080ec2d4a8e707e) [0.25 hours: 5cdb08bfb0798752b039c5ba]
* Daily scrum. (Meetings: 5cdb08ead278ae206156ae6f) [0.25 hours: 5cdb090bb0798752b039c5f6]
0.5 hours.
In the output each line under "Time entries" that begins with a `*` is a time
entry. The time entry's description is first shown, then the entry's project
name and ID, then the hours spent and the time entry's ID.
The default behavior of the list command is to display all time entries with a
start date that's within a date range. When the `--strict` option is used,
however, both the start date and end date must be within the date range.
To get more information, per time entry, the `--verbose` (or `-v`) option can
be used. This will display date and time for each entry as well as the parent
project of any entry that is associated with a task rather than a project.
Here's an example of listing yesterday's time entries:
./cft list yesterday
Yesterday is one time period of a number of available time periods.
Note that there are one letter abbreviations for the periods. The abbreviation
for "yesterday" is "y", for example.
`cft` commands like "list" can have one letter abbreviations. So if you
wanted to list yesterday's time entries you could enter:
./cft l y
Another time saver: if you enter a time period, instead of a command, you'll
get a list of entries in the time period:
./cft y
### List time entries in an arbitrary date range
When listing time entries, an arbitrary date range can be specified using the
`--start` (or `-s-`) and/or `--end` (or `-e`) options.
If either `--start` or `--end` are specified, but the other isn't, then the
one that's omitted they will default to today's date.
Example list of time entries in an arbitary date range:
./cft l -s 2019-03-06 --e 2019-03-09
The `-` or `+` operators, as a prefix to a integeter represeting a number of
days, can also be used to indicate a relative date.
For example, if one wanted to list time entries created five days ago to the
present day then one could use this command:
./cft l -s -5
### List projects
The `projects` (or `p`) command is used to list projects. The project name
and ID will be output.
For example:
$ ./cft projects
* Email [5cdb08621080ec2d4a8e707e]
* Meetings [5cdb08ead278ae206156ae6f]
### Project details
The `project` (or `pd`) command is used to display details about a project,
including a list of tasks for it.
For example:
$ ./cft project ed5c600955e74cce9648cd91
Name: Example Company - Hosting
Client: Example
Tasks:
* Support [5d8bff9dad3d0047ca62e3fd]
### Task details
The `task` (or `td`) command is used to display details about a task.
For example:
$ ./cft task 5d8bff9dad3d0047ca62e3fd
Name: Support
Project ID: ed5c600955e74cce9648cd91
### Creating a time entry
The `new` (or `n`) command is used to create a new time entry. The number of
hours, rather than a particular time range, is specified.
Help for the new command:
$ ./cft new -h
usage: cft new [-h] [-c comments: required for new time entries]
[-t hours spent: required for new time entries] [-d date] [-b]
[-s start time]
project ID
positional arguments:
project ID ID of project or task: required
optional arguments:
-h, --help show this help message and exit
-c comments: required for new time entries, --comments comments: required for new time entries
-t hours spent: required for new time entries, --hours hours spent: required for new time entries
-d date, --date date defaults to today
-b, --billable
-s start time, --start start time
Here's an example (in which `5cb772f3f15c9857ee275d00` is the project ID:
./cft new 5cb772f3f15c9857ee275d00 --comments="Checking email." --hours=.25
Here's the same example in a briefer form.
./cft n 5cb772f3f15c9857ee275d00 -c "Checking email." -t .25
When specifying a date, the `+` or `-` operators are relative to the current
date. If you create a time entry today that should be dated as yesteray you
could update it with `-1` as the date to fix.
For example:
./cft n 5cb772f3f15c9857ee275d00 -c "Checking email." -t .25 -d -1
If specifying a start time, using the `--start`/`-s` optional argument, the
time should be specified in 24 hour time format.
For example:
./cft n 5cb772f3f15c9857ee275d00 -c "Checking email." -t .25 -s 13:15
Note that when adding a time entry the current time will be used as the start
time unless a date and/or start time are specified. If a date is specified, but
a start time isn't, then the start time will be midnight. If a start time is
specified, however, then the specified start time will be used.
### Deleting a time entry
The `delete` (or `d`) command is used to delete a time entry.
Here's an example (in which `5cd64137b079870300a9c9e0` is the time entry ID:
./cft delete 5cd64137b079870300a9c9e0
### List workspaces
The `workspaces` (or `w`) command is used to list workspaces. The workspace
name and ID will be output.
For example:
$ ./cft workspaces
* Client-Project-Task Workspace [4c31a29da059321c02e301e0]
### Cache status/flushing
You probably won't need to use this, but it exists. The `cache` command is used
to display how many time entries have been cached. The `--flush` (or `-f`) flag
can be used to delete all cached time entries.
## Advanced configuration
You can save time entering time entries by using advanced configuration.
### Project time entry aliases
When specifying a project, or project task, you can either use ID of the
project or you can refer to an alias specifed in your configuration file. You
can also create aliases for aliases.
Example:
projects:
meet:
id: 4cb771f3f13c9855ee275d00
meeting:
id: meet
### Project time entry templates
In addition to using an alias to specify a project, or project task, ID, you
can use the same technique to, when creating a time entry, automatically set
the comments and hours spent.
Example:
projects:
meet:
id: 100
meeting:
id: meet
scrum:
id: meet
comments: "Daily scrum."
hours: .25
These values can be overridden by command-line options so if, building on the
previous example, you had a scrum meeting that lasted a half hour, instead of
15 minutes, you could add a time entry using the "scrum" alias and just
overrride the --time command-line option.
Example:
./cft n scrum -t .5
### Shortcuts and abbreviations
Example of quick addition of a time entry using a template:
./cft +scrum
Raw data
{
"_id": null,
"home_page": "https://github.com/artefactual-labs/clockify-tool",
"name": "clockifytool",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "clockify",
"author": "Mike Cantelon",
"author_email": "mcantelon@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ff/db/3ef8069aa52a6275ee977aeb359bf26c3647df6f07bf8e8e568c003a5af0/clockifytool-0.1.0.tar.gz",
"platform": null,
"description": "# clockify-tool\n\nThe Clockify Tool (`cft`) can be used to list, create, and delete time entries\nin Clockify.\n\nWith `cft` you can make use of time entry \"templates\" (see `Advanced\nconfiguration`) to rapidly create time entries. For example if you regularly\nhave a 15 minute scrum meeting you could create a \"scrum\" time entry template\nthat allows you to add a time entry like this:\n\n ./cft +scrum\n\n## Installation\n\nInstall via PyPi:\n\n pip install clockifytool\n\n...Or clone this repo, change into the repo directory, then enter the following\ncommand:\n\n pip install -r requirements/base.txt\n\n## Basic Configuration\n\nTo use `cft` you'll need to, in the Clockify web UI, click the \"GENERATE\"\nbutton on the \"Personal settings\" page to generate an API key. You'll then need\nto put the key into the `cft` configuration file, which is YAML-formatted and\nmust be created in `$HOME/.cft.yml`.\n\nHere's an example configuration file containing an API key:\n\n api key: aLedJtL4rl48s2O7\n\nOnce you've created a configuration file, you can then run `cft` which will\nprovide you will a list of available workspaces.\n\nFor example:\n\n $ ./cft\n Please set workspace ID as \"workspace\" in /home/vagrant/.cft.yml.\n \n Available workspaces:\n * Client-Project-Task Workspace [4c31a29da059321c02e301e0]\n\nEdit the configuration file to set the ID of the workspace you'd like to use.\n\nExample configuration with API key and workspace set:\n\n api key: aLedJtL4rl48s2O7\n workspace: 4c31a29da059321c02e301e0\n\nRead on to learn about the basic functionality of `cft` and, once you've got\nthe hang of things, check out `Advanced Configuration` to learn how you can\nsave time when entering new time entries.\n\n## Commands\n\nClockify Tool allows you to list, create and delete Clockify time entries. You\ncan also list projects, project tasks, and workspaces to find out their IDs.\n\n### Listing time entries in a period of time\n\nHelp for the list command:\n\n $ ./cft list -h\n usage: cft list [-h] [-s start date] [-e end date] [--strict] [-v] [period]\n \n positional arguments:\n period time period: optional, overrides -s and -e\n \n optional arguments:\n -h, --help show this help message and exit\n -s start date, --start start date\n -e end date, --end end date\n --strict\n -v, --verbose\n \n Available periods: \"yesterday\" (\"y\"): day before today, \"daybeforeyesterday\"\n (\"dby\"): day before yesterday, \"lastweek\" (\"lw\"): last work week (Monday to\n Friday), \"currentweek\" (\"cw\"): current work week (Monday to Friday),\n \"fulllastweek\" (\"flw\"): last full week (Sunday to Saturday), \"fullcurrentweek\"\n (\"fcw\"): current full week (Sunday to Saturday), \"lastmonth\" (\"lm\"): last\n month, \"currentmonth\" (\"cm\"): current month, \"lastyear\" (\"ly\"): last year,\n \"currentyear\" (\"cy\"): current year, \"monday\" (\"mon\"): Monday, \"tuesday\"\n (\"tue\"): Tuesday, \"wednesday\" (\"wed\"): Wednesday, \"thursday\" (\"thu\"):\n Thursday, \"friday\" (\"fri\"): Friday, \"saturday\" (\"sat\"): Saturday, \"sunday\"\n (\"sun\"): Sunday, \"lastmonday\" (\"lmon\"): Last Monday, \"lasttuesday\" (\"ltue\"):\n Last Tuesday, \"lastwednesday\" (\"lwed\"): Last Wednesday, \"lastthursday\"\n (\"lthu\"): Last Thursday, \"lastfriday\" (\"lfri\"): Last Friday, \"lastsaturday\"\n (\"lsat\"): Last Saturday, \"lastsunday\" (\"lsun\"): Last Sunday,\n \"currentpayperiod\" (\"cp\"): current pay period, \"previouspayperiod\" (\"pp\"):\n previous pay period\n\nExample list of today's time entries:\n\n ./cft\n\nHere's example output:\n\n $ ./cft \n Fetching time entries from 2020-02-13 (Thursday)...\n \n Time entries:\n * Reading email. (Email: 5cdb08621080ec2d4a8e707e) [0.25 hours: 5cdb08bfb0798752b039c5ba]\n * Daily scrum. (Meetings: 5cdb08ead278ae206156ae6f) [0.25 hours: 5cdb090bb0798752b039c5f6]\n \n 0.5 hours.\n\nIn the output each line under \"Time entries\" that begins with a `*` is a time\nentry. The time entry's description is first shown, then the entry's project\nname and ID, then the hours spent and the time entry's ID.\n\nThe default behavior of the list command is to display all time entries with a\nstart date that's within a date range. When the `--strict` option is used,\nhowever, both the start date and end date must be within the date range.\n\nTo get more information, per time entry, the `--verbose` (or `-v`) option can\nbe used. This will display date and time for each entry as well as the parent\nproject of any entry that is associated with a task rather than a project.\n\nHere's an example of listing yesterday's time entries:\n\n ./cft list yesterday\n\nYesterday is one time period of a number of available time periods.\n\nNote that there are one letter abbreviations for the periods. The abbreviation\nfor \"yesterday\" is \"y\", for example.\n\n`cft` commands like \"list\" can have one letter abbreviations. So if you\nwanted to list yesterday's time entries you could enter:\n\n ./cft l y\n\nAnother time saver: if you enter a time period, instead of a command, you'll\nget a list of entries in the time period:\n\n ./cft y\n\n### List time entries in an arbitrary date range\n\nWhen listing time entries, an arbitrary date range can be specified using the\n`--start` (or `-s-`) and/or `--end` (or `-e`) options.\n\nIf either `--start` or `--end` are specified, but the other isn't, then the\none that's omitted they will default to today's date.\n\nExample list of time entries in an arbitary date range:\n\n ./cft l -s 2019-03-06 --e 2019-03-09\n\nThe `-` or `+` operators, as a prefix to a integeter represeting a number of\ndays, can also be used to indicate a relative date.\n\nFor example, if one wanted to list time entries created five days ago to the\npresent day then one could use this command:\n\n ./cft l -s -5\n\n### List projects\n\nThe `projects` (or `p`) command is used to list projects. The project name\nand ID will be output.\n\nFor example:\n\n $ ./cft projects\n * Email [5cdb08621080ec2d4a8e707e]\n * Meetings [5cdb08ead278ae206156ae6f]\n\n### Project details\n\nThe `project` (or `pd`) command is used to display details about a project,\nincluding a list of tasks for it.\n\nFor example:\n\n $ ./cft project ed5c600955e74cce9648cd91\n Name: Example Company - Hosting\n Client: Example\n \n Tasks:\n * Support [5d8bff9dad3d0047ca62e3fd]\n\n### Task details\n\nThe `task` (or `td`) command is used to display details about a task.\n\nFor example:\n\n $ ./cft task 5d8bff9dad3d0047ca62e3fd\n Name: Support\n Project ID: ed5c600955e74cce9648cd91\n\n### Creating a time entry\n\nThe `new` (or `n`) command is used to create a new time entry. The number of\nhours, rather than a particular time range, is specified.\n\nHelp for the new command:\n\n $ ./cft new -h\n usage: cft new [-h] [-c comments: required for new time entries]\n [-t hours spent: required for new time entries] [-d date] [-b]\n [-s start time]\n project ID\n \n positional arguments:\n project ID ID of project or task: required\n \n optional arguments:\n -h, --help show this help message and exit\n -c comments: required for new time entries, --comments comments: required for new time entries\n -t hours spent: required for new time entries, --hours hours spent: required for new time entries\n -d date, --date date defaults to today\n -b, --billable\n -s start time, --start start time\n\nHere's an example (in which `5cb772f3f15c9857ee275d00` is the project ID:\n\n ./cft new 5cb772f3f15c9857ee275d00 --comments=\"Checking email.\" --hours=.25\n\nHere's the same example in a briefer form.\n\n ./cft n 5cb772f3f15c9857ee275d00 -c \"Checking email.\" -t .25\n\nWhen specifying a date, the `+` or `-` operators are relative to the current\ndate. If you create a time entry today that should be dated as yesteray you\ncould update it with `-1` as the date to fix.\n\nFor example:\n\n ./cft n 5cb772f3f15c9857ee275d00 -c \"Checking email.\" -t .25 -d -1\n\nIf specifying a start time, using the `--start`/`-s` optional argument, the\ntime should be specified in 24 hour time format.\n\nFor example:\n\n ./cft n 5cb772f3f15c9857ee275d00 -c \"Checking email.\" -t .25 -s 13:15\n\nNote that when adding a time entry the current time will be used as the start\ntime unless a date and/or start time are specified. If a date is specified, but\na start time isn't, then the start time will be midnight. If a start time is\nspecified, however, then the specified start time will be used.\n\n### Deleting a time entry\n\nThe `delete` (or `d`) command is used to delete a time entry.\n\nHere's an example (in which `5cd64137b079870300a9c9e0` is the time entry ID:\n\n ./cft delete 5cd64137b079870300a9c9e0\n\n### List workspaces\n\nThe `workspaces` (or `w`) command is used to list workspaces. The workspace\nname and ID will be output.\n\nFor example:\n\n $ ./cft workspaces\n * Client-Project-Task Workspace [4c31a29da059321c02e301e0]\n\n### Cache status/flushing\n\nYou probably won't need to use this, but it exists. The `cache` command is used\nto display how many time entries have been cached. The `--flush` (or `-f`) flag\ncan be used to delete all cached time entries.\n\n## Advanced configuration\n\nYou can save time entering time entries by using advanced configuration.\n\n### Project time entry aliases\n\nWhen specifying a project, or project task, you can either use ID of the\nproject or you can refer to an alias specifed in your configuration file. You\ncan also create aliases for aliases.\n\nExample:\n\n projects:\n meet:\n id: 4cb771f3f13c9855ee275d00\n meeting:\n id: meet\n\n### Project time entry templates\n\nIn addition to using an alias to specify a project, or project task, ID, you\ncan use the same technique to, when creating a time entry, automatically set\nthe comments and hours spent.\n\nExample:\n\n projects:\n meet:\n id: 100\n meeting:\n id: meet\n scrum:\n id: meet\n comments: \"Daily scrum.\"\n hours: .25\n\nThese values can be overridden by command-line options so if, building on the\nprevious example, you had a scrum meeting that lasted a half hour, instead of\n15 minutes, you could add a time entry using the \"scrum\" alias and just\noverrride the --time command-line option.\n\nExample:\n\n ./cft n scrum -t .5\n\n### Shortcuts and abbreviations\n\nExample of quick addition of a time entry using a template:\n\n ./cft +scrum\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tool to list, create, and delete time entries in Clockify",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/artefactual-labs/clockify-tool"
},
"split_keywords": [
"clockify"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f9778811179669830ee00ba24ec6f38194529cfa3e6fab4c06beed48a66a6a80",
"md5": "dd595156c119361c41debb52c704b185",
"sha256": "1de156b81417c327a121f445f2d99cda404c9113a315cf38f9c44e27c8b5eec7"
},
"downloads": -1,
"filename": "clockifytool-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd595156c119361c41debb52c704b185",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16264,
"upload_time": "2023-12-06T07:02:27",
"upload_time_iso_8601": "2023-12-06T07:02:27.121776Z",
"url": "https://files.pythonhosted.org/packages/f9/77/8811179669830ee00ba24ec6f38194529cfa3e6fab4c06beed48a66a6a80/clockifytool-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ffdb3ef8069aa52a6275ee977aeb359bf26c3647df6f07bf8e8e568c003a5af0",
"md5": "0223f053174c37870affcc557752d0da",
"sha256": "8413e8be02793853d54546d68270e3db95bf546d6fa6c68865e431246d2b7881"
},
"downloads": -1,
"filename": "clockifytool-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0223f053174c37870affcc557752d0da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18175,
"upload_time": "2023-12-06T07:02:29",
"upload_time_iso_8601": "2023-12-06T07:02:29.282301Z",
"url": "https://files.pythonhosted.org/packages/ff/db/3ef8069aa52a6275ee977aeb359bf26c3647df6f07bf8e8e568c003a5af0/clockifytool-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-06 07:02:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "artefactual-labs",
"github_project": "clockify-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "clockifytool"
}
JSON
