akctl

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 Kurigram (a maintained Pyrogram fork; imported as pyrogram). Its tgcrypto dependency gives it fast native crypto, so uploads are noticeably quicker than pure-Python alternatives. 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.

For pasarguard, the database is dumped too: it reads SQLALCHEMY_DATABASE_URL out of /opt/pasarguard/.env and runs pg_dump (PostgreSQL) or mysqldump/mariadb-dump (MySQL/MariaDB) — whichever the URL's scheme calls for — adding the .sql file to the archive alongside the folders. Requires the matching client tool on PATH (apt install postgresql-client / default-mysql-client); if it's missing or the dump fails, that's logged as a warning and the folder backup still goes ahead. The .env file itself (with the DB credentials) is already included as part of /opt/pasarguard, so keep the resulting archive as private as the server it came from.

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 is bounded by a hard timeout (SEND_TIMEOUT_SECONDS, 900s) so a blocked/unreachable network fails eventually instead of hanging forever — 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.

kurigram (and its tgcrypto speed-up) are core dependencies, installed automatically with akctl — no extra install step needed. tgcrypto ships prebuilt wheels for common platforms; on one without a wheel it needs a C compiler at install time.

Roadmap

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

License

MIT — see LICENSE.