Metadata-Version: 2.5
Name: akctl
Version: 0.1.6
Summary: A simple CLI toolkit for everyday server management tasks
Project-URL: Homepage, https://github.com/AmirKenzo/ak-cli
Project-URL: Repository, https://github.com/AmirKenzo/ak-cli
Project-URL: Issues, https://github.com/AmirKenzo/ak-cli/issues
Author: AmirKenzo
License-Expression: MIT
License-File: LICENSE
Keywords: backup,cli,monitoring,server,sysadmin,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: <3.15,>=3.11
Requires-Dist: cryptg>=0.6.0
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=13.0
Requires-Dist: telethon>=1.44.0
Provides-Extra: all-backends
Requires-Dist: kurigram>=2.0; extra == 'all-backends'
Requires-Dist: pytdbot[tdjson]>=0.10; extra == 'all-backends'
Requires-Dist: tgcrypto>=1.2; extra == 'all-backends'
Provides-Extra: kurigram
Requires-Dist: kurigram>=2.0; extra == 'kurigram'
Requires-Dist: tgcrypto>=1.2; extra == 'kurigram'
Provides-Extra: pytdbot
Requires-Dist: pytdbot[tdjson]>=0.10; extra == 'pytdbot'
Description-Content-Type: text/markdown

# ak-cli

A small CLI I built for my own server management needs — quick answers to
"what's using the RAM", "is this port open", "how full is the disk", without
reaching for a full monitoring stack. Sharing it in case it's useful to
someone else too.

Every command works both as a direct CLI call and from an interactive menu,
so you can script it or just run `ak` and pick from a list.

## Features

| Command         | Description                                   |
| --------------- | ---------------------------------------------- |
| `system-info`   | OS, architecture, Python version, hostname     |
| `disk-usage`    | Usage for every mounted disk/partition         |
| `network-info`  | IPv4 address of every network interface        |
| `memory-info`   | RAM and swap usage                             |
| `cpu-info`      | Core count, current usage, frequency           |
| `process-list`  | Top processes by memory usage                  |
| `uptime`        | System boot time and uptime                    |
| `users`         | Currently logged-in users                      |
| `port-check`    | Check whether a TCP port on a host is open     |
| `backup-init`   | Create a backup config template                |
| `backup`        | Archive configured folders and send to Telegram|

## Requirements

- Python 3.11+

## Installation

Clone the repo and install it in a virtual environment. [uv](https://docs.astral.sh/uv/)
is recommended:

```bash
git clone https://github.com/AmirKenzo/ak-cli.git
cd ak-cli
uv sync
uv run ak
```

Or with plain `pip`:

```bash
git clone https://github.com/AmirKenzo/ak-cli.git
cd ak-cli
python -m venv .venv
.venv/Scripts/activate   # on Linux/macOS: source .venv/bin/activate
pip install -e .
ak
```

## Usage

Running `ak` with no arguments opens the interactive menu:

```bash
ak
```

Every command is also available directly, which is handy for scripts and
one-liners:

```bash
ak system-info
ak disk-usage
ak memory-info
ak cpu-info
ak process-list --limit 5
ak port-check example.com 443
ak uptime
ak users
```

### Backups

`ak backup` archives an explicit target — a known type or a folder path — into
a `.tar.gz` and sends it to a Telegram chat via [Telethon](https://docs.telethon.dev/).
A target is always required, so it never silently sends something you didn't ask for:

```bash
ak backup                    # error: target is required
ak backup pasarguard         # backs up /opt/pasarguard + /var/lib/pasarguard, nothing else
ak backup /etc/nginx         # backs up an arbitrary folder
ak backup pasarguard --keep  # also save the archive in the current directory
```

Known types live in `BACKUP_TYPES` in [src/ak/backup.py](src/ak/backup.py)
(currently just `pasarguard`); anything else passed as the target is treated
as a literal folder path.

```bash
ak backup-init   # interactive wizard: prompts for telegram creds, saves to ~/.config/ak/backup.json
```

If you skip `backup-init` and just run `ak backup <target>` in a terminal, it
prompts you for the Telegram bot token/chat ID on the spot (and offers to save
them) instead of failing. `api_id`/`api_hash` default to Telegram Desktop's
public API credentials if left unset, so only `bot_token` and `chat_id` are
needed. They can also be passed as flags for one-off/scripted runs:

```bash
ak backup pasarguard --bot-token "<token>" --chat-id -1001234567890
```

Config can also be provided entirely via environment variables — useful for
cron/systemd, where there's no terminal to prompt on:
`AK_TG_API_ID`, `AK_TG_API_HASH`, `AK_TG_BOT_TOKEN`, `AK_TG_CHAT_ID`, and
`AK_BACKUP_CONFIG` to point at a non-default config file location.

The upload connects with a short per-attempt timeout and few retries so a
blocked/unreachable network fails fast (within `SEND_TIMEOUT_SECONDS`, 900s)
instead of hanging — if your server can't reach Telegram directly at all
(common when self-hosting in regions that filter it), no client-side setting
fixes that; you'd need a proxy in front of it.

#### Sending backend

Three libraries can do the actual upload; pick with `--backend` or
`AK_BACKUP_BACKEND` (default: `telethon`) to compare speed on your network:

```bash
ak backup pasarguard --backend telethon    # default, no extra install
ak backup pasarguard --backend kurigram    # Pyrogram-compatible fork
ak backup pasarguard --backend pytdbot     # official TDLib, via pytdbot
```

Each backend needs its library installed — `ak backup` reports the exact
command if it's missing. **The speed-up packages are separate installs that
`pip`/`uv` won't pull in unless you ask for the extra**, so don't skip them:

| Backend    | Install                                    | Speed-up package (don't skip)                          |
| ---------- | ------------------------------------------- | -------------------------------------------------------- |
| `telethon` | `pip install akctl` (already the default)  | `cryptg` — already included                              |
| `kurigram` | `pip install 'akctl[kurigram]'`            | `tgcrypto` — included in the extra, needs a C compiler on platforms without a prebuilt wheel |
| `pytdbot`  | `pip install 'akctl[pytdbot]'`             | `tdjson` — included in the extra, ships a prebuilt TDLib binary for common platforms |

Or install everything at once: `pip install 'akctl[all-backends]'` /
`uv tool install 'akctl[all-backends]'`.

Notes:
- `kurigram` is a maintained Pyrogram fork (same `pyrogram` import, same API);
  without `tgcrypto` it still works, just slower (pure-Python crypto).
- `pytdbot` wraps the official TDLib and needs a local encrypted database
  directory (`~/.config/ak/pytdbot/` by default) — this is TDLib's own
  requirement, not something this CLI adds.
- `telethon`/`kurigram` fail fast on a blocked/dead connection (few retries,
  short per-attempt timeout). `pytdbot` doesn't expose that knob — on a
  fully blocked network it can retry internally for the full
  `SEND_TIMEOUT_SECONDS` before giving up, unlike the other two.

## Roadmap

- Scheduled (cron) backup runs
- Including database dumps alongside the folder backups

## License

MIT — see [LICENSE](LICENSE).
