telectl
GitHub Releases GHCR
Edit this page on GitHub

Quick Start

Get telectl running in five minutes — from nothing to your first /resources view in Telegram.

What you need

  • A Kubernetes cluster you can reach (kubectl cluster-info works).
  • A Telegram bot token from @BotFather.
  • Your Telegram user ID (ask @userinfobot).
  • The telectl binary (or a container image).

1. Create a bot with BotFather

  1. Open @BotFather, send /newbot, pick a name and username.
  2. Copy the token it gives you — it looks like 123456789:AA....

2. Get your user ID

Message @userinfobot. It replies with your numeric ID. You must put this ID in the config — without it, the bot will refuse to talk to you.

3. Write a config file

# ~/.config/telectl/telectl.yaml
telegram:
  bot_token: "YOUR_BOT_TOKEN"
  allowed_user_ids: [YOUR_USER_ID]   # e.g. [YOUR_ADMIN_TELEGRAM_ID]

kubernetes:
  kubeconfig_path: "~/.kube/config"  # optional; defaults to $KUBECONFIG

The bot searches config in this order: ~/.config/telectl/telectl.yaml, ~/.config/telectl.yaml, /etc/telectl/telectl.yaml, or an explicit --config path. See Configuration Reference.

4. Run it

telectl

You should see:

INFO  Starting telectl   {"version": "0.1.0-beta.0", "commit": "...", "dry_run": false}

If you see No allowed users configured, every Telegram user who finds the bot can operate your cluster. Fix allowed_user_ids before going further.

5. Open the chat

  1. Find your bot on Telegram and press Start.
  2. Tap the ☰ menu button (or send /resources).
  3. Pick a resource type — Pods — and browse.

Try these next:

Command What it does
/get pods -A list pods in every namespace
/logs <pod> --tail 50 last 50 log lines of a pod
/top pods pod CPU/memory (needs metrics-server)
/contexts switch cluster from the kubeconfig
/config show the effective config (redacted)

Securing it (don’t skip)

  • The bot holds your kubeconfig permissions. A leaked bot token is a leaked cluster credential — keep bot_token out of version control.
  • If multiple people use the bot, enable per-user RBAC via Impersonation & RBAC so each user only gets their own role.
  • For production hardening see the Production Checklist.

Next steps