infeeeee/kimai2-cmd

Command line client for Kimai2, the open source, self-hosted time tracker

⚠️ UNMAINTAINED ⚠️

PRs will be accepted, but issues won't be fixed.

Alternative maintained clients:

• Kimai-console: Another cli app
• Kemai: Graphical client

Kimai2-cmd

Command line client for Kimai2, the open source, self-hosted time tracker.

To use this program you have to install Kimai2 first!

Features

This client is not intended to replace the Kimai webUI, so only basic functions, starting and stopping measurements

Commands:

• Start, restart and stop measurements
• List active and recent measurements
• List projects and activities

UI:

• Interactive terminal UI with autocomplete
• Classic terminal UI for integration

Integration:

• Portable executable for all three platforms
• Installer for Windows
• Generate output for Rainmeter (Windows). More info here: kimai2-cmd-rainmeter
• Generate output for Argos/Kargos/Bitbar (Gnome, Kde, Mac). More info here: kimai2-cmd-argos

Requests for integrations with other softwares are welcomed! Just open an issue and show an example output, what you need.

Installation

Download from releases.

You have to create an API password for your username on your Kimai installation. In Kimai: User menu (Top right corner) -> Edit -> API.

Notes on Windows

Portable executable or installer available.

Installer automatically adds the install path to the %PATH% environment variable, so you can use it from command line/powershell system wide. Sign out and in if it's not working.

With the portable version you have to do this manually. Follow this tutorial or a similar one if you don't know how to do it.

Notes on Linux/Mac

Portable executable only. On the following terminal examples use the file name you downloaded.

Make the downloaded binary executable:

sudo chmod +x kimai2-cmd-os

Add kimai2-cmd to path so you have to just type kimai to the terminal:

sudo ln -s /path/to/kimai2-cmd-os /usr/bin/kimai

To remove:

sudo rm /usr/bin/kimai

Install with npm

If npm installed you can install it with the following command:

npm install -g infeeeee/kimai2-cmd

Usage

Two usage modes: interactive and classic ui

Interactive ui

If you start without any commands, you will get to the interactive UI. Use your keyboard's arrow keys for navigation. On the Start new measurement menu item you can search for project and activity names.

You can exit with ctrl+c any time.

Classic ui

You can find all the options in the help:

$ kimai2-cmd --help

Usage: kimai2-cmd [options] [command]

Command line client for Kimai2. For interactive mode start without any commands. To generate settings file start in interactive mode!

Options:
  -V, --version               output the version number
  -v, --verbose               verbose, longer logging
  -i, --id                    show id of elements when listing
  -b, --argosbutton           argos/bitbar button output
  -a, --argos                 argos/bitbar output
  -h, --help                  output usage information

Commands:
  start [project] [activity]  start selected project and activity
  restart [id]                restart selected measurement
  stop [id] [description]     stop all or selected measurement measurements, [id] is optional, [description] is optional but needs [id]
  rainmeter                   update rainmeter skin
  list-active                 list active measurements
  list-recent                 list recent measurements
  list-projects               list all projects
  list-activities             list all activities
  url                         prints the url of the server

Project and activity names are case insensitive. If your project or activity name contains a space, wrap it in double or single quotes. This example starts project named foo with activity named bar bar:

kimai2-cmd start "foo" "bar bar"

Settings and first run

All settings stored in the settings.ini file. Place this file to the same directory as the executable. If no settings file found you will drop to the interactive UI, where you can add your settings:

You can create your settings.ini file manually, by downloading, renaming and editing settings.ini.example.

On the windows installer version settings.ini location: C:\Users\Username\AppData\Roaming\kimai2-cmd\settings.ini

You can also store the settings.ini file in custom location, just export the full path to the KIMAI_CONFIG variable, something like this:

export KIMAI_CONFIG=$XDG_CONFIG_HOME/kimai2/settings.ini

Integration settings are not asked during first run, you have to change them manually in settings.ini. If you don't use an integration, you can safely ignore it's settings.

Development version

Installation

Prerequisites:

• node js 10+
• git

git clone https://github.com/infeeeee/kimai2-cmd
cd kimai2-cmd
npm i

Build

Prerequisite: globally installed pkg:

npm i pkg -g

Build for current platform and architecture

npm run build-current

Build x64 executables for linux, mac on linux or on mac

npm run build-nix

About building for other platforms see pkg's documentation, or open an issue and I can build it for you.

Installer (Windows only)

Prerequisite: Inno Setup

• Create a windows build: npm run build-current
• Open kimai2-innosetup.iss in Inno Setup

Usage

For interactive mode just simply:

npm start

For usage with options you have pass a -- before the options. You don't need this if you don't use options just commands:

npm start -- -V
npm start start foo bar

On the first run it will ask for your settings, but you can just copy settings.ini.example to settings.ini and modify it with your favorite text editor

Troubleshooting

If you find a bug open an issue here!

License

MIT

kimai2-cmd's Issues

SyntaxError: Unexpected token < in JSON at position 0

Hello,
I've cloned the most recent version
node kimai2-cmd.js -V
0.2.5
node v11.15.0
npm v6.11.2
Linux 4.19.66-1-MANJARO

[serversettings]
kimaiurl=https://server.ch/kimai2/public
username=myuser
password=mypassword

if I'm understanding correctly my access logs, the settings.ini is correct because i've got redirected (Code 302) and logged in (code 200), isn't it ?

server.ch XX.XX.XXX.XXXX - - [04/Sep/2019:13:39:57 +0200] "GET /kimai2/public/en/login HTTP/1.1" 200 3865 "https://server.ch/kimai2/public/api/projects" "-"

server.ch XX.XX.XXX.XXXX - - [04/Sep/2019:13:39:56 +0200] "GET /kimai2/public/api/projects HTTP/1.1" 302 420 "-" "-"

I can launch the menu

But any selected function but Exit creates following error messages

Hosting (https://www.infomaniak.com/)
Kimai 2 1.2 stable (Ayumi)
Debian 4.9.168-1+deb9u3~deb8u1 (2019-06-17) x86_64 GNU/Linux
PHP 7.3.8
mysql Ver 14.14 Distrib 5.5.62, for debian-linux-gnu (x86_64) using readline 6.3

Thank you for any possible help

SyntaxError: Unexpected end of JSON input

When i want to start a measurement:

undefined:1



SyntaxError: Unexpected end of JSON input
    at JSON.parse (<anonymous>)
    at Request.request [as _callback] (/snapshot/kimai2-cmd/kimai2-cmd.js:84:32)
    at Request.init.self.callback (/snapshot/kimai2-cmd/node_modules/request/request.js:185:22)
    at Request.emit (events.js:198:13)
    at Request.<anonymous> (/snapshot/kimai2-cmd/node_modules/request/request.js:1161:10)
    at Request.emit (events.js:198:13)
    at IncomingMessage.<anonymous> (/snapshot/kimai2-cmd/node_modules/request/request.js:1083:12)
    at Object.onceWrapper (events.js:286:20)
    at IncomingMessage.emit (events.js:203:15)
    at endReadableNT (_stream_readable.js:1145:12)

When using the cli with the linux executable. I'm on arch 6.7.5.

I want to point that all the settings are correct, and i'm able to list the projects from the remote

Exceptions of stop of measurement(s) if currently no measurements are running

Thank you for the nice cli. It works fine, but I just had an issue with the cli when no measurement is going on, but I want to stop it.

Situation: No measurement is currently runnning.

Situation A:
Selecting "Stop all active measurements"

Expected:
Message: "Currently no measurements were running." and return to menu, like at "List active measurements".

Result:

(node:1124) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'id' of undefined
    at Promise (/snapshot/kimai2-cmd/kimai2-cmd.js:320:55)
    at new Promise (<anonymous>)
    at callKimaiStop (/snapshot/kimai2-cmd/kimai2-cmd.js:318:12)
    at kimaiList.then.res (/snapshot/kimai2-cmd/kimai2-cmd.js:300:28)
    at process._tickCallback (internal/process/next_tick.js:68:7)
(node:1124) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 2)
(node:1124) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

and I need to restart the tool.

Situation B:
Select "Stop an active measurement". This shows no running measurments, but allows to select/enter which leads to an error:

Expected:
same as above.

Result:

(node:1136) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'value' of undefined
    at ListPrompt.getCurrentValue (/snapshot/kimai2-cmd/node_modules/inquirer/lib/prompts/list.js:121:53)
    at MapSubscriber._next (/snapshot/kimai2-cmd/node_modules/rxjs/internal/operators/map.js:0:0)
    at MapSubscriber.Subscriber.next (/snapshot/kimai2-cmd/node_modules/rxjs/internal/Subscriber.js:66:18)
    at TakeSubscriber._next (/snapshot/kimai2-cmd/node_modules/rxjs/internal/operators/take.js:0:0)
    at TakeSubscriber.Subscriber.next (/snapshot/kimai2-cmd/node_modules/rxjs/internal/Subscriber.js:66:18)
    at Interface.handler (/snapshot/kimai2-cmd/node_modules/rxjs/internal/observable/fromEvent.js:22:28)
    at Interface.emit (events.js:194:15)
    at Interface._onLine (readline.js:290:10)
    at Interface._line (readline.js:638:8)
    at Interface._ttyWrite (readline.js:919:14)
(node:1136) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:1136) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

and I need to restart the tool.

Cannot read property 'body' of undefined

Hello,

I have the latest Kimai version with a certificate from internal CA (so untrusted by new devices) which is trusted on my PC.

I use Linux Ubuntu 22.04 as OS.

Installed CLI tool version: 1.3.0

When I try to use this CLI tool, I get this error:

>> kimai2-cmd -v
No environment variable found
Looking for settings.ini in the following places:
{ pkg: '/home/jonah/.local/bin', npm: '/snapshot/kimai2-cmd' }
settings.ini found at: /home/jonah/.local/bin/settings.ini

? Select command Start new measurement
selected answer: start
---
calling kimai:  GET projects [object Object]
request options: [object Object]
/snapshot/kimai2-cmd/kimai2-cmd.js:84
            let jsonarr = JSON.parse(response.body)
                                              ^

TypeError: Cannot read property 'body' of undefined
    at Request.request [as _callback] (/snapshot/kimai2-cmd/kimai2-cmd.js:84:47)
    at Request.init.self.callback (/snapshot/kimai2-cmd/node_modules/request/request.js:185:22)
    at Request.emit (events.js:198:13)
    at Request.onRequestError (/snapshot/kimai2-cmd/node_modules/request/request.js:881:8)
    at ClientRequest.emit (events.js:198:13)
    at TLSSocket.socketErrorListener (_http_client.js:401:9)
    at TLSSocket.emit (events.js:198:13)
    at emitErrorNT (internal/streams/destroy.js:91:8)
    at emitErrorAndCloseNT (internal/streams/destroy.js:59:3)
    at process._tickCallback (internal/process/next_tick.js:63:19)

Any idea?

Add config environment variable

Could you add an environment variable, e.g. KIMAI_CONFIG, which stores the path to the settings.ini?
Then kimai2-cmd could first search for the settings.ini in the path provided by KIMAI_CONFIG and then in its own folder.

With an environment variable I could do something like this:
export KIMAI_CONFIG=$XDG_CONFIG_HOME/kimai2

Starting a project only works with ui

kimai2-cmd start "Foo" "Bar" -v -i

Results in

Found in KIMAI_CONFIG envvar: /home/beavis/.config/kimai2/settings.ini
settings.ini found at: /home/beavis/.config/kimai2/settings.ini
---
calling kimai:  GET projects [object Object]
request options: [object Object]
Response body: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]
---
calling kimai:  GET activities [object Object]
request options: [object Object]
Response body: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]
---
calling kimai:  GET config/i18n [object Object]
request options: [object Object]
kimaistart calling api: [object Object]
---
calling kimai:  POST timesheets [object Object]
request options: [object Object]
Response body: [object Object]
Server error message:
400
Validation Failed
(node:488024) UnhandledPromiseRejectionWarning: Validation Failed
(Use `node --trace-warnings ...` to show where the warning was created)
(node:488024) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)
(node:488024) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
Response body: [object Object]
servertime: 2021-11-22T15:36:47+0100
localtime: 2021-11-22T15:36:47+01:00