Metadata-Version: 2.4
Name: kolay-cli
Version: 0.6.0
Summary: Command-line interface for Kolay IK (https://apidocs.kolayik.com)
Author: Tunc Aucer
License-Expression: MIT
Project-URL: Homepage, https://github.com/ezapmar/kolay-cli
Project-URL: Repository, https://github.com/ezapmar/kolay-cli
Project-URL: Issues, https://github.com/ezapmar/kolay-cli/issues
Keywords: kolay,hr,cli,kolayik,human-resources
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.4.2
Dynamic: license-file

# kolay-cli

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

A command-line interface for the [Kolay IK API](https://apidocs.kolayik.com).
Manage employees, leaves, transactions, calendar events, and more — from your terminal.

---

## Installation

```bash
pipx install kolay-cli
```

Or with pip:

```bash
pip install kolay-cli
```

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

---

## Getting Started

```bash
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:

```bash
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:
```bash
kolay auth login
```

Or via environment variable (takes precedence over the config file):
```bash
export KOLAY_API_TOKEN=your_token_here
```

### Base URL

The default API base URL is `https://api.kolayik.com`. Override if needed:
```bash
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

- All API communication uses HTTPS with a verified TLS connection.
- The API token is stored with restricted file permissions (`0600`).
- The `KOLAY_API_TOKEN` environment variable overrides the file and is never written to disk.
- All requests include a 30-second timeout.
- Error messages from the API are translated to English and sanitised before display.

---

## Development

```bash
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:
```bash
pip install bandit
bandit -r src/
```

---

## License

MIT — see [LICENSE](LICENSE).

---

## Links

- [Kolay IK API Documentation](https://apidocs.kolayik.com)
- [GitHub Repository](https://github.com/ezapmar/kolay-cli)
- [PyPI Package](https://pypi.org/project/kolay-cli/)
- [Report an Issue](https://github.com/ezapmar/kolay-cli/issues)
