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

Requirements

• Python 3.11+

Installation

Clone the repo and install it in a virtual environment. uv is recommended:

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

Or with plain pip:

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:

ak

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

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. A target is always required, so it never silently sends something you didn't ask for:

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 (currently just pasarguard); anything else passed as the target is treated as a literal folder path.

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:

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:

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:

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.