kolay-cli 0.7.0

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

kolay-cli

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

A command-line interface for the Kolay IK API. Manage employees, leaves, transactions, calendar events, and more — from your terminal.

---

Installation

pipx install kolay-cli

Or with pip:

pip install kolay-cli

Recommended: Use pipx to install CLI tools in isolated environments.

---

Getting Started

kolay auth login

You will be prompted to enter your Kolay API token. The token is stored at ~/.config/kolay/config.json with 0600 permissions (read/write for owner only).

Verify your session at any time:

kolay auth status
kolay auth me

---

Commands

auth

Command	Description
kolay auth login	Save and verify your API token
kolay auth status	Show current login status and user name
kolay auth me	Show your full profile

---

person

Command	Description
kolay person list	List employees (default: active)
kolay person list --status inactive	List terminated employees
kolay person list --search "ali"	Search by name or email
kolay person view <id>	View full profile of an employee
kolay person summary <id>	View summary of an employee
kolay person leave-status <id>	View leave balances
kolay person update <id>	Update employee profile fields
kolay person terminate <id>	Terminate an employee with reason code

---

leave

Command	Description
kolay leave list	List approved leaves for this year
kolay leave list --status waiting	List pending leave requests
kolay leave list --person-id <id>	Filter by employee
kolay leave view <id>	View a specific leave record
kolay leave create	Create a new leave request (interactive)

---

transaction

Command	Description
kolay transaction list	List all transactions
kolay transaction list --type bonus	Filter by type
kolay transaction list --status waiting	Filter by approval status
kolay transaction view <id>	View a specific transaction
kolay transaction create	Create a new transaction
kolay transaction delete <id>	Delete a transaction (with confirmation)

Supported transaction types: advancePayment, overtime, bonus, premium, otherCut, militaryBenefit, nationalHolidayBenefit, fuelAllowanceBenefit

---

calendar

Command	Description
kolay calendar list	List events for the next 30 days
kolay calendar list --start 2026-01-01 --end 2026-12-31	List events in a date range
kolay calendar list --search "meeting"	Search events by title
kolay calendar view <id>	View a specific event
kolay calendar create	Create a new event (interactive)
kolay calendar update <id>	Update an event (prefills current values)
kolay calendar delete <id>	Delete an event (with confirmation)

---

Configuration

API Token

Set via interactive login:

kolay auth login

Or via environment variable (takes precedence over the config file):

export KOLAY_API_TOKEN=your_token_here

Base URL

The default API base URL is https://api.kolayik.com. Override if needed:

export KOLAY_BASE_URL=https://custom.domain.com

The base URL must use HTTPS. HTTP is rejected to prevent credential exposure.

Config File

Tokens are stored at:

~/.config/kolay/config.json

File permissions are set to 0600 on creation (owner read/write only).

---

Security

• HTTPS enforced: The base URL must start with https://. HTTP is rejected at startup to prevent Bearer token transmission over plaintext.
• Token storage: The config file (~/.config/kolay/config.json) is created atomically with 0600 permissions using os.open() -- there is no window where the file is world-readable before chmod.
• No token echo: The token is never printed to the terminal, even partially. Login prompts use hide_input=True.
• Input validation: All user-supplied IDs are validated against [a-zA-Z0-9_-] before URL interpolation to prevent path traversal attacks (../../).
• Endpoint sanitization: The API client rejects endpoints containing .., absolute paths, or embedded :// schemes.
• Request timeouts: All HTTP requests enforce a 30-second timeout to prevent indefinite hangs.
• Error sanitization: API error messages are cleaned before display. No raw HTTP responses or stack traces are shown to the user.
• Environment variable precedence: KOLAY_API_TOKEN overrides the config file and is never written to disk.
• Dependency pinning: Build dependencies are pinned to patched versions (setuptools>=78.1.1) to avoid known CVEs.

---

Development

git clone https://github.com/ezapmar/kolay-cli
cd kolay-cli
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
kolay --version

Run security audit:

pip install bandit
bandit -r src/

---

License

MIT — see LICENSE.

---

Links

• Kolay IK API Documentation
• GitHub Repository
• PyPI Package
• Report an Issue