kolay-cli 0.3.0

Command-line interface for Kolay IK (https://apidocs.kolayik.com)

Kolay CLI

                        +************
                       +*+        **+
                      +*+       +*+      %%               #%%
                     +*+       +*+       %%   *#*  #%%#   #%%   #%%#*#*+**    **+
                   +**+       +*+        %% #%%* %%%##%%% #%% %%%#*%%%% %%#  #%%
                    **+      +**+        %%%%#  %%#    %%##%%#%%    %%%  %%##%%#
                     +*+    +*++*+       %%#%%# %%%    %%##%%*%%    #%%   %%%%#
                      +*+  **   +*+      %%  #%% *%%%%%%# #%% #%%%%%%%%   *%%%
                       +*+**      **+                                     #%%
                        +************                                   #%%%

A powerful, user-friendly command-line interface for the Kolay IK API. Manage your HR operations directly from the terminal.

✨ Features

Module	Commands	Description
Auth	login, status	Securely store and manage your API token
Person	list, view, leave-status, terminate	List employees, view structured profiles, check leave balances, terminate with SGK codes
Leave	list, view, create	List leave records, view details, create leaves with interactive type picker

Highlights

• 🎨 Rich terminal output — Structured tables, panels, and color-coded statuses
• 🔐 Secure token storage — Config file with restricted permissions (0600)
• 🇹🇷 Turkish HR aware — SGK termination codes, DD.MM.YYYY date format support
• ⚡ Smart prompts — Leave type picker, today's date defaults, active employee pre-checks

📦 Installation

Using pipx (Recommended)

pipx install kolay-cli

From source

git clone https://github.com/ezapmar/kolay-cli.git
cd kolay-cli
pip install -e .

🚀 Quick Start

1. Authenticate

Generate an API token from Kolay Developer Settings, then:

kolay auth login

2. List your employees

kolay person list

3. View someone's profile

kolay person view <person-id>

4. Check leave balances

kolay person leave-status <person-id>

5. Create a leave request

kolay leave create

The CLI will interactively show available leave types and let you pick by number.

📖 Command Reference

Auth

kolay auth login          # Save your API token (prompted securely)
kolay auth status         # Check if you're logged in

Person

kolay person list                          # List active employees
kolay person list --status inactive        # List inactive employees
kolay person list --page 2                 # Paginate results
kolay person view <id>                     # Structured profile view
kolay person leave-status <id>             # Leave balances table
kolay person terminate <id>                # Terminate with SGK reason codes

Leave

kolay leave list                           # List approved leaves (current year)
kolay leave list --status waiting          # List pending leaves
kolay leave list --person-id <id>          # Filter by person
kolay leave list --start-date "2025-01-01 00:00:00" --end-date "2025-12-31 23:59:59"
kolay leave view <leave-id>               # View leave record details
kolay leave create                         # Interactive leave creation

⚙️ Configuration

The CLI stores its configuration at ~/.config/kolay/config.json with restricted file permissions.

You can also use environment variables (they take precedence):

export KOLAY_API_TOKEN="your-token-here"
export KOLAY_BASE_URL="https://api.kolayik.com"  # optional

🛠 Development

# Clone and setup
git clone https://github.com/ezapmar/kolay-cli.git
cd kolay-cli
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e .

# Run
kolay --help

📄 License

This project is licensed under the MIT License — use it freely, modify it, share it. See the LICENSE file for details.