kevinpapst / kimai2-console
Kimai - console application to manage your time-tracking data remotely
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 4
Forks: 1
Open Issues: 5
Type:project
Requires
- php: 8.1.*||8.2.*
- ext-curl: *
- ext-iconv: *
- ext-json: *
- ext-mbstring: *
- kimai/api-php: ^1.0
- symfony/console: 6.*
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.2
- phpstan/phpstan: ^1.0
README
A PHP application to access your Kimai 2 installation via its API (http).
Requirements
- Kimai > v2.0.20
- PHP 8.1 or 8.2
- cURL extension
- json extension
- iconv extension
- zlib extension
- mbstring extension
Installation
To install the Kimai console tools, execute the following commands:
curl -LO https://github.com/kevinpapst/kimai2-console/releases/latest/download/kimai.phar curl -LO https://github.com/kevinpapst/kimai2-console/releases/latest/download/kimai.phar.sha1 sha1sum --check kimai.phar.sha1 rm kimai.phar.sha1 chmod +x kimai.phar mv kimai.phar /usr/local/bin/kimai
Configuration file
Before using it the first time, you have to create a configuration file, which holds the connection infos for Kimai.
By default this config file will be located at ~/.kimai2-console.json
:
kimai configuration
Make sure the file is only readable for your own user:
chmod 600 ~/.kimai2-console.json
That's it, you can use Kimai from the command line now.
By default, the configuration file targets the demo installation and will work... but now it's time to target your own Kimai, so please edit the config file and change the settings:
URL
: the Kimai installation URLUSERNAME
: the Kimai installation URLAPI_KEY
: your Kimai API key (can be set when editing your profile)OPTIONS
: an array of request options for CURL (see guzzle docs)
FAQ:
I want to use a self-signed certificate
- add"OPTIONS": {"verify": false}
to your configuration
Available commands
You get a list of all available commands with kimai
.
kimai active
- display and update all running timesheets (via--description
and--tags
)kimai stop
- stop currently active timesheets and update them (via--description
and--tags
)kimai start
- start a new timesheet (see below)kimai customer:list
- show a list of customerskimai project:list
- show a list of projectskimai activity:list
- show a list of activitieskimai version
- show the full version string of the remote installationkimai configuration
- creates the initial configuration file or displays it
To get help for a dedicated command use the --help
switch, eg: kimai project:list --help
Start a timesheet
This command tries to detect customer, project and activity from your input in the following way:
- if it is a number, then it tries to load the entity by its ID
- if a entity is found, it will be used
- if it is a string, then this is just as search term
- if one entity is found, it will be used
- if multiple entities are found, a select list is shown
- if nothing is given or no result was found in the previous steps, a list of all entities is fetched and shown for selection
- this list might be filtered (eg. only activities for found project)
This most simple example will display a select list for all customers, then a filtered list for the projects of the chosen customer and finally a select list for all activities for the chosen project:
bin/kimai start
Example to start a new timesheet by search terms only, adding a description and some tags:
bin/kimai start --customer Schowalter --project analyzer --activity iterate --description "working for fun" --tags "test, bla foo, tagging"
[OK] Started timesheet
------------- ------------------------------------
ID 5085
Begin 2020-01-03T23:34:26+0100
Description working for fun
Tags bla foo
test
tagging
Customer Schowalter PLC
Project Grass-roots system-worthy analyzer
Activity iterate viral infomediaries
------------- ------------------------------------
Output format
The :list
ing commands display a formatted table of all found entities.
If you want to use the output in a script, instead of manually looking at them, please use the --csv
switch.
Environment variables
The following environment variables are supported:
KIMAI_MEMORY_LIMIT
- configures the allowed memory limit (eg128MB
, or-1
for unlimited) (see here)KIMAI_CONFIG
- path to your configuration file (defaults to: $HOME/.kimai2-console.json)
FAQ
Updating the Console tools
Redo the initial installation process and overwrite the file /usr/local/bin/kimai
with the latest release.
Check the contents of the PHAR
There are several ways to see the contents of the PHAR, here are some:
phar extract -f kimai.phar
box info kimai.phar -l
The PHAR contents are GZ compressed and verified with a SHA512 signature by the PHAR interpreter.
Build from source
You need to have PHP cli installed with all required dependencies. The dependencies might differ from than the ones required for running the tools. Then install the humbug/box project, according to their installation docs.
Now compiling the PHAR is as simple as calling:
box compile
Release on GitHub
- Bump version in
src/Constants.php
- Execute
composer install --no-dev
- Execute
box compile
- Execute
sha1sum kimai.phar > kimai.phar.sha1
- Prepare a new GitHub release
- Upload the files
kimai.phar
andkimai.phar.sha1
to the new release - Publish the release