telegram-tools 3.2.0__tar.gz → 3.3.0__tar.gz

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/.github/pull_request_template.md

@@ -7,6 +7,7 @@
 - [ ] I did not include Telegram API hashes, bot tokens, phone numbers, `.env`, session files, or private exports.
 - [ ] I did not make destructive Telegram operations easier to run accidentally.
 - [ ] If I touched `clear-messages`, dry-run, `--execute`, typed `DELETE`, topic preservation, and topic ID preservation are covered by tests.
+- [ ] If I touched `send`, the preview + `y/N` and the `TELEGRAM_SEND_ALLOWLIST` gate on `--yes` are covered by tests.
 
 ## Validation
 

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/.github/workflows/tests.yml

@@ -46,5 +46,7 @@ jobs:
           telegram-tools discover --help
           telegram-tools clear-messages --help
           telegram-tools search --help
+          telegram-tools send --help
+          telegram-tools create --help
           telegram-tools bots --help
           telegram-tools doctor --help

telegram_tools-3.3.0/AGENTS.md

@@ -0,0 +1,15 @@
+# telegram-tools — agent brief
+
+Local Telethon CLI operating the user's own Telegram account: `discover` chat/topic IDs, `search`/export messages, `send` a message, `create` group/channel/topic, `clear-messages`, `bots` (BotFather settings), `doctor`. Public repo — contributor-facing; never commit phone numbers, API hashes, tokens, or exported chat data (CONTRIBUTING.md binds).
+
+## Working here
+- Test: `.venv/bin/python -m pytest -q` → all pass (300 as of v3.3.0), no network. CI adds `compileall` + per-subcommand `--help` smoke; there is no lint step.
+- Bare invocation is the human menu; agents pass a subcommand. Session + exports live in `~/.telegram-tools/`, outside the repo.
+- `skill/SKILL.md` (independently versioned) is the bundled agent skill's source of truth: a CLI-surface change updates it **in the same commit** — convention, nothing enforces it.
+- A user-visible fix also gets its CHANGELOG entry and version bump in the same change; unreleased fixes silently stacking on the last shipped version is the failure mode to avoid.
+
+## Destructive commands
+`clear-messages` deletes real messages: dry-run is the default, execution needs `--execute` plus typed `DELETE`. `bots` mutates live bot settings behind a diff + confirm (`--yes` skips). `send` posts publicly as the user behind a full-message preview + `y/N`; its `--yes` additionally requires the destination in `TELEGRAM_SEND_ALLOWLIST` (unset = every `--yes` send refused). `create` confirms before making a real, visible object. Keep those gates, and keep the menu from ever being the shorter path past one.
+
+## Releasing (maintainer only)
+PyPI account is **banozz** (not the GitHub handle). Full recipe with the zsh traps (the `!` negation, the glob no-op, stale-sdist check, twine output redaction) lives in the maintainer's private runbook. Rebuild `dist/` after any source edit; `repo ≠ sdist` — `docs/superpowers/` is tracked here but excluded from the package.

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented here.
 
 This project follows a practical changelog style: user-visible changes, safety changes, and release notes belong here; active task tracking belongs outside the repo.
 
+## 3.3.0 - 2026-08-25
+
+- Add `send`: post a message to a chat, or into one forum topic with `--topic`. It prints the destination and the whole message body, then asks `y/N`. `--text -` reads the body from stdin, which is how a multi-line message gets in without fighting your shell.
+- Add `create`: `create group` (a supergroup, with `--forum` to switch topics on in the same call), `create channel` (a broadcast channel), and `create topic` (a topic inside a forum group). Each asks before it acts and prints the new ID, so a new chat can be piped straight into `send`.
+- Both are in the menu, at 3 and 4. The other entries moved down: clearing topic messages is now 5, bots 6, check setup 7. The menu has no `--yes` equivalent — every send it makes shows the message and asks.
+- New optional `TELEGRAM_SEND_ALLOWLIST` (`chat[:topic]`, comma separated). It gates one thing only: `send --yes`, the unattended path where nobody sees the preview. Unset means every `--yes` send is refused; `send` without `--yes` is unaffected. `doctor` reports how many destinations are listed and never which.
+- The menu's staged message shows in the prompt when you go back to it (`Message [hiiiii]`), so keeping it does not mean typing it again. Long or multi-line bodies are flattened and cut for that one line only.
+- No attachments on `send` — text only for now.
+
 ## 3.2.0 - 2026-08-15
 
 - `telegram-tools` with no arguments now opens a menu you walk forward and back through instead of a single screen that exits after one action: numbered lists all the way down, `0` always backs out one screen at a time — inside a picker or a flow's own screen alike — and a return to the menu after every job.

telegram_tools-3.3.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/CONTRIBUTING.md

@@ -35,6 +35,8 @@ telegram-tools --help
 telegram-tools discover --help
 telegram-tools clear-messages --help
 telegram-tools search --help
+telegram-tools send --help
+telegram-tools create --help
 telegram-tools bots --help
 telegram-tools doctor --help
 ```
@@ -45,6 +47,18 @@ If you have local Telegram config and session storage, also run:
 telegram-tools doctor
 ```
 
+## Send Changes
+
+`send` posts publicly as the person running it, so its gates are load-bearing:
+
+- Without `--yes`, the whole message and its resolved destination are printed and a
+  `y/N` is required.
+- `--yes` skips that prompt and therefore requires the destination to appear in
+  `TELEGRAM_SEND_ALLOWLIST`. An unset allowlist refuses every `--yes` send.
+- The menu never passes `--yes`.
+
+Keep all three covered by tests.
+
 ## Clear-Message Changes
 
 Be especially conservative around `clear-messages`.

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: telegram-tools
-Version: 3.2.0
+Version: 3.3.0
 Summary: Local Telethon CLI for Telegram chat/topic ID discovery, message search/export, topic message clearing, and bot settings editing.
 Project-URL: Homepage, https://github.com/banozz0/telegram-tools
 Project-URL: Repository, https://github.com/banozz0/telegram-tools
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 
 # telegram-tools
 
-A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, and clear all messages out of forum topics without destroying the topics themselves.
+A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, send a message into a chat or topic, create groups/channels/topics, and clear all messages out of forum topics without destroying the topics themselves.
 
 Built on [Telethon](https://github.com/LonamiWebs/Telethon). Everything runs on your machine with your own Telegram API credentials — no server, no third party, nothing leaves your computer except the Telegram API calls you asked for.
 
@@ -58,14 +58,16 @@ Built on [Telethon](https://github.com/LonamiWebs/Telethon). Everything runs on
 - **`discover`** — lists your chats, channels, and forum groups with their exact numeric IDs and every forum topic ID. The fastest way to answer "what is this chat's `-100…` ID and what are its topic IDs?"
 - **`search`** — searches messages by text, sender, date range, or topic, and prints a table or exports JSON/CSV.
 - **`clear-messages`** — deletes all messages inside selected forum topic(s) while preserving the topics and their IDs. Dry-run by default; deleting requires both `--execute` *and* typing `DELETE` at a prompt.
+- **`send`** — posts a message to a chat, or into one forum topic. Shows you the whole message and its destination, then asks `y/N`.
+- **`create`** — makes a supergroup (optionally with topics already on), a broadcast channel, or a topic inside a forum group, and prints the new ID.
 - **`bots`** — lists the bots you own with their numeric IDs, and edits what @BotFather edits: display name, bio, description, commands, profile photo, and default admin rights.
 - **`doctor`** — checks your local setup without printing any secrets.
 
 ## What it doesn't do (on purpose)
 
-- No deleting or creating forum topics — topic IDs never change.
-- No media downloads.
-- No sending messages and no automation loops. The `bots` command edits bot *settings*; it never runs a bot.
+- No deleting forum topics, and no renaming them — `clear-messages` leaves topic IDs untouched.
+- No media downloads, and no attachments on `send` — text only.
+- No automation loops. The `bots` command edits bot *settings*; it never runs a bot.
 - No changing a bot's `@username`, creating or deleting bots, or reading/revoking bot tokens — those stay with @BotFather.
 - No cloud anything — credentials and session files stay in `~/.telegram-tools/`.
 
@@ -113,6 +115,21 @@ TELEGRAM_BOT_TOKENS=mybot:12345:AAExampleToken,alerts:67890:BBExampleToken
 
 Nicknames are yours to choose and can be used as `--bot mybot`. The tool only ever reads this variable — it never writes a token anywhere, and never prints one.
 
+### Optional: the send allowlist
+
+`send` asks you to confirm every message. `--yes` skips that prompt, and because a
+skipped prompt means nobody saw where the message was going, it only works for
+destinations you have named in advance:
+
+```bash
+# in ~/.telegram-tools/.env
+TELEGRAM_SEND_ALLOWLIST=-1001234567890:141,-1009876543210,@myalerts
+```
+
+Each entry is a chat ID or `@username`, optionally `:topic-id` to allow just one topic
+in it. Unset means every `--yes` send is refused — `send` without `--yes` still works
+and still asks. `doctor` reports how many destinations are listed, never which.
+
 ## 30 seconds of usage
 
 ```bash
@@ -131,6 +148,16 @@ telegram-tools clear-messages --chat @mygroup --topic 141
 # Actually delete: needs --execute AND typing DELETE at the prompt
 telegram-tools clear-messages --chat @mygroup --topic 141 --execute
 
+# Send a message into a topic (shows it, then asks y/N)
+telegram-tools send --chat -1001234567890 --topic 141 --text "deploy is green"
+
+# Multi-line body, straight from a file or a pipe
+cat notes.txt | telegram-tools send --chat -1001234567890 --text -
+
+# Make a group with topics already switched on, then a topic in it
+telegram-tools create group --title "Agency" --forum
+telegram-tools create topic --chat -1001234567890 --title "Deploys"
+
 # Which bots do I own, and what are their IDs?
 telegram-tools bots
 
@@ -170,9 +197,11 @@ telegram-tools
 --------------------------------------------
 1. Chats & topics (find IDs)
 2. Search / export messages
-3. Clear topic messages
-4. My bots
-5. Check setup
+3. Send a message
+4. Create a group, channel, or topic
+5. Clear topic messages
+6. My bots
+7. Check setup
 0. Exit
 ```
 
@@ -183,14 +212,17 @@ you to type an ID. Bot fields show their current value and offer keep / change /
 clear. After every job it returns to the menu.
 
 The safety gates are the same as the flags', not looser: clearing topic messages
-dry-runs first and still asks you to type `DELETE`, and bot edits still print a diff
-and ask before writing. With no terminal attached it prints this help instead.
+dry-runs first and still asks you to type `DELETE`, sending shows the whole message
+and asks `y/N`, and bot edits still print a diff and ask before writing. The menu has
+no equivalent of `--yes` at all. With no terminal attached it prints this help instead.
 
 ## Safety model
 
 | Command | Destructive? |
 | --- | --- |
 | `discover`, `search`, `doctor` | No — read-only |
+| `create` | No — makes new things, changes nothing existing, after a `y/N` unless you pass `--yes` |
+| `send` | Outward-facing — posts publicly as you, after showing the whole message and asking `y/N`. `--yes` skips the prompt only for destinations in `TELEGRAM_SEND_ALLOWLIST` |
 | `bots` | No — changes settings on bots you own, after a diff and a `y/N` unless you pass `--yes`; reversible if you still have the old values, but `--remove-photo` and `--clear-commands` discard data Telegram will not hand back |
 | `clear-messages` | Yes — but only with `--execute` **and** a typed `DELETE`, only messages, never topics |
 
@@ -200,7 +232,7 @@ and ask before writing. With no terminal attached it prints this help instead.
 
 ## Status
 
-Stable for its four jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.
+Stable for its six jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.
 
 ## License
 

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/README.md

@@ -1,6 +1,6 @@
 # telegram-tools
 
-A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, and clear all messages out of forum topics without destroying the topics themselves.
+A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, send a message into a chat or topic, create groups/channels/topics, and clear all messages out of forum topics without destroying the topics themselves.
 
 Built on [Telethon](https://github.com/LonamiWebs/Telethon). Everything runs on your machine with your own Telegram API credentials — no server, no third party, nothing leaves your computer except the Telegram API calls you asked for.
 
@@ -9,14 +9,16 @@ Built on [Telethon](https://github.com/LonamiWebs/Telethon). Everything runs on
 - **`discover`** — lists your chats, channels, and forum groups with their exact numeric IDs and every forum topic ID. The fastest way to answer "what is this chat's `-100…` ID and what are its topic IDs?"
 - **`search`** — searches messages by text, sender, date range, or topic, and prints a table or exports JSON/CSV.
 - **`clear-messages`** — deletes all messages inside selected forum topic(s) while preserving the topics and their IDs. Dry-run by default; deleting requires both `--execute` *and* typing `DELETE` at a prompt.
+- **`send`** — posts a message to a chat, or into one forum topic. Shows you the whole message and its destination, then asks `y/N`.
+- **`create`** — makes a supergroup (optionally with topics already on), a broadcast channel, or a topic inside a forum group, and prints the new ID.
 - **`bots`** — lists the bots you own with their numeric IDs, and edits what @BotFather edits: display name, bio, description, commands, profile photo, and default admin rights.
 - **`doctor`** — checks your local setup without printing any secrets.
 
 ## What it doesn't do (on purpose)
 
-- No deleting or creating forum topics — topic IDs never change.
-- No media downloads.
-- No sending messages and no automation loops. The `bots` command edits bot *settings*; it never runs a bot.
+- No deleting forum topics, and no renaming them — `clear-messages` leaves topic IDs untouched.
+- No media downloads, and no attachments on `send` — text only.
+- No automation loops. The `bots` command edits bot *settings*; it never runs a bot.
 - No changing a bot's `@username`, creating or deleting bots, or reading/revoking bot tokens — those stay with @BotFather.
 - No cloud anything — credentials and session files stay in `~/.telegram-tools/`.
 
@@ -64,6 +66,21 @@ TELEGRAM_BOT_TOKENS=mybot:12345:AAExampleToken,alerts:67890:BBExampleToken
 
 Nicknames are yours to choose and can be used as `--bot mybot`. The tool only ever reads this variable — it never writes a token anywhere, and never prints one.
 
+### Optional: the send allowlist
+
+`send` asks you to confirm every message. `--yes` skips that prompt, and because a
+skipped prompt means nobody saw where the message was going, it only works for
+destinations you have named in advance:
+
+```bash
+# in ~/.telegram-tools/.env
+TELEGRAM_SEND_ALLOWLIST=-1001234567890:141,-1009876543210,@myalerts
+```
+
+Each entry is a chat ID or `@username`, optionally `:topic-id` to allow just one topic
+in it. Unset means every `--yes` send is refused — `send` without `--yes` still works
+and still asks. `doctor` reports how many destinations are listed, never which.
+
 ## 30 seconds of usage
 
 ```bash
@@ -82,6 +99,16 @@ telegram-tools clear-messages --chat @mygroup --topic 141
 # Actually delete: needs --execute AND typing DELETE at the prompt
 telegram-tools clear-messages --chat @mygroup --topic 141 --execute
 
+# Send a message into a topic (shows it, then asks y/N)
+telegram-tools send --chat -1001234567890 --topic 141 --text "deploy is green"
+
+# Multi-line body, straight from a file or a pipe
+cat notes.txt | telegram-tools send --chat -1001234567890 --text -
+
+# Make a group with topics already switched on, then a topic in it
+telegram-tools create group --title "Agency" --forum
+telegram-tools create topic --chat -1001234567890 --title "Deploys"
+
 # Which bots do I own, and what are their IDs?
 telegram-tools bots
 
@@ -121,9 +148,11 @@ telegram-tools
 --------------------------------------------
 1. Chats & topics (find IDs)
 2. Search / export messages
-3. Clear topic messages
-4. My bots
-5. Check setup
+3. Send a message
+4. Create a group, channel, or topic
+5. Clear topic messages
+6. My bots
+7. Check setup
 0. Exit
 ```
 
@@ -134,14 +163,17 @@ you to type an ID. Bot fields show their current value and offer keep / change /
 clear. After every job it returns to the menu.
 
 The safety gates are the same as the flags', not looser: clearing topic messages
-dry-runs first and still asks you to type `DELETE`, and bot edits still print a diff
-and ask before writing. With no terminal attached it prints this help instead.
+dry-runs first and still asks you to type `DELETE`, sending shows the whole message
+and asks `y/N`, and bot edits still print a diff and ask before writing. The menu has
+no equivalent of `--yes` at all. With no terminal attached it prints this help instead.
 
 ## Safety model
 
 | Command | Destructive? |
 | --- | --- |
 | `discover`, `search`, `doctor` | No — read-only |
+| `create` | No — makes new things, changes nothing existing, after a `y/N` unless you pass `--yes` |
+| `send` | Outward-facing — posts publicly as you, after showing the whole message and asking `y/N`. `--yes` skips the prompt only for destinations in `TELEGRAM_SEND_ALLOWLIST` |
 | `bots` | No — changes settings on bots you own, after a diff and a `y/N` unless you pass `--yes`; reversible if you still have the old values, but `--remove-photo` and `--clear-commands` discard data Telegram will not hand back |
 | `clear-messages` | Yes — but only with `--execute` **and** a typed `DELETE`, only messages, never topics |
 
@@ -151,7 +183,7 @@ and ask before writing. With no terminal attached it prints this help instead.
 
 ## Status
 
-Stable for its four jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.
+Stable for its six jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.
 
 ## License
 

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/docs/telethon-api-notes.md

@@ -21,3 +21,10 @@ Checked on 2026-08-13 for the `bots` command (Telethon 1.44.0):
 - `photos.deletePhotos` needs an `InputPhoto` with an access hash, which `UserProfilePhoto` does not carry; fetch the photo through `photos.getUserPhotos` and convert it with `telethon.utils.get_input_photo`.
 - `bots.exportBotToken` exists and would let an owner read a bot's token. This project never calls it: it sits next to a `revoke` flag, and reading credentials is outside what the tool does.
 - Changing a bot's `@username`, creating a bot, and deleting a bot have no user-facing API and remain @BotFather-only.
+
+Checked on 2026-08-25 for the `send` and `create` commands (Telethon 1.44.0):
+
+- `TelegramClient.send_message(entity, message, reply_to=...)` posts into a forum topic by passing the topic id as `reply_to` — a topic *is* its root message thread, so there is no separate topic parameter.
+- `channels.CreateChannelRequest` covers both a supergroup (`megagroup=True`) and a broadcast channel (`broadcast=True`), and takes a `forum` flag. Passing `forum=True` at creation avoids a second `channels.ToggleForumRequest` round trip, and with it the window where a group exists but the toggle failed.
+- `messages.CreateForumTopicRequest` lives under `messages`, not `channels` (unlike `ToggleForumRequest`). Its `random_id` is auto-generated when omitted.
+- Neither create request returns the created object directly. `CreateChannelRequest` returns `Updates` whose `chats[0]` is the new channel — `telethon.utils.get_peer_id` converts it to the marked `-100…` form. `CreateForumTopicRequest` returns `Updates` carrying only the topic's service message; that message's `id` **is** the new topic id.

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "telegram-tools"
-version = "3.2.0"
+version = "3.3.0"
 description = "Local Telethon CLI for Telegram chat/topic ID discovery, message search/export, topic message clearing, and bot settings editing."
 readme = "README.md"
 requires-python = ">=3.11"

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/skill/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: telegram-tools
-description: "Use when you need the real numeric ID of a Telegram chat, channel, group or forum topic — 'what's the ID of that topic?', 'which chat is -100…?', 'where do I send this?' — or when the user wants their own Telegram messages searched or exported to JSON/CSV."
-version: 1.1.0
+description: "Use when you need the real numeric ID of a Telegram chat, channel, group or forum topic — 'what's the ID of that topic?', 'which chat is -100…?', 'where do I send this?' — when the user wants their own Telegram messages searched or exported to JSON/CSV, or when a message must be posted to a chat or topic the user has allowlisted."
+version: 1.2.0
 author: banozz0
 license: MIT
 platforms: [macos]
 metadata:
   hermes:
-    tags: [telegram, chat-ids, topic-ids, forum, search, export, cli]
+    tags: [telegram, chat-ids, topic-ids, forum, search, export, send, cli]
 ---
 
 # telegram-tools
@@ -40,8 +40,9 @@ their own message history searched, filtered or exported. It is the fastest way
 settle "which thread does this go to?", which is the single most common cause of a
 message being delivered into a topic nobody reads.
 
-It does not send messages, run bots, download media, or create and delete topics.
-Anything that *posts* to Telegram belongs to a bot token and a different tool.
+It can also **send** a message and **create** a group, channel or topic. Those write
+to Telegram as the user, so rules 2 and 3 below govern them — read those before
+running either. It still does not run bots, download media, or delete topics.
 
 ## Hard rules
 
@@ -49,18 +50,31 @@ Anything that *posts* to Telegram belongs to a bot token and a different tool.
 it is their user account, the same one their friends message. Reads are read-only and
 fine. Anything that writes is theirs to run, not yours.
 
-**2. Never run `clear-messages`.** It deletes real messages out of their forum topics
+**2. `send` only goes where the user already said it may.** `send --yes` posts with
+no human in the loop, and the CLI refuses it for any destination not in the user's
+`TELEGRAM_SEND_ALLOWLIST`. That refusal is the whole safety model — do not work
+around it by dropping `--yes` (which would block on a `y/N` prompt no agent can
+answer), by editing the user's `.env`, or by picking a different chat. A destination
+that is not allowlisted is a destination the user has not approved: draft the message,
+show it to them, and let them send it or add the entry.
+
+**3. Never run `create` unprompted.** New groups, channels and topics are real,
+visible objects in the user's Telegram — other people see them appear. Create one only
+when the user asked for that specific thing in this conversation, and never invent a
+title. `create` outside an explicit ask is theirs to run, not yours.
+
+**4. Never run `clear-messages`.** It deletes real messages out of their forum topics
 and Telegram does not undo that. Dry-run is its default and the destructive path
 needs both `--execute` and a typed confirmation, so you will not trip it by accident
 — but do not run it at all, in any form, even to preview. If the answer is "those
 messages should go", say so and let the user run it.
 
-**3. Never print the credentials.** `TELEGRAM_API_ID`, `TELEGRAM_API_HASH` and the
+**5. Never print the credentials.** `TELEGRAM_API_ID`, `TELEGRAM_API_HASH` and the
 `.session` file are secrets. Point at where they live; never read them out, copy
 them, or paste them into a reply. `doctor` exists precisely so setup can be checked
 without any of that reaching the screen.
 
-**4. If the CLI errors, say so.** A login prompt, a flood-wait, an expired session —
+**6. If the CLI errors, say so.** A login prompt, a flood-wait, an expired session —
 that *is* the answer. Never guess a chat ID. A made-up `-100…` sends the user's next
 alert into the void, and they will not find out until something they needed never
 arrived.
@@ -76,6 +90,10 @@ arrived.
 | "find where X was discussed" | `telegram-tools search --chat <id> --keyword "X"` |
 | "everything in that topic since Monday" | `telegram-tools search --chat <id> --topic <topic-id> --since 2026-08-10` |
 | "export it" | `telegram-tools search --chat <id> --format csv --output /path/out.csv` |
+| "post this to that topic" (allowlisted) | `telegram-tools send --chat <id> --topic <topic-id> --text "..." --yes` |
+| a long or multi-line message | pipe it: `... \| telegram-tools send --chat <id> --text - --yes` |
+| "make me a group with topics" (they asked) | `telegram-tools create group --title "..." --forum --yes` |
+| "add a topic to that group" (they asked) | `telegram-tools create topic --chat <id> --title "..." --yes` |
 | "is telegram-tools set up?" | `telegram-tools doctor` |
 
 - **`discover` defaults to admin/managed chats only** — the ones the user runs. Add
@@ -87,6 +105,14 @@ arrived.
   Narrow with `--topic`, `--keyword`, `--from-user` (a username, an ID, or `me`),
   `--since` / `--until` (ISO dates), and `--limit`. With no `--output` it prints a
   readable table, which is usually what you want to summarise from.
+- **`send` needs `--yes` from an agent session, and `--yes` needs the allowlist.**
+  Without `--yes` it prints the message and waits for a `y/N` nobody is there to
+  type. With `--yes` it refuses anything outside `TELEGRAM_SEND_ALLOWLIST` and the
+  error names the destination to add — relay that to the user verbatim rather than
+  retrying. `doctor` says how many destinations are listed, never which.
+- **`send --topic` is the difference between delivered and lost.** Omitting it posts
+  to the chat itself, not the thread. Confirm the topic ID with `discover` first;
+  never guess one.
 - **Check the tool's own help before using a flag** that is not in this table. The
   CLI's `--help` is current; this file is a snapshot.
 - **The menu is for the human at the keyboard.** `telegram-tools` with no arguments
@@ -95,7 +121,10 @@ arrived.
 
 ## Never run these
 
-- **`clear-messages`** — irreversible deletion of the user's messages. Rule 2 above.
+- **`clear-messages`** — irreversible deletion of the user's messages. Rule 4 above.
+- **`create` on your own initiative** — rule 3. If a new group or topic looks like
+  the right answer, propose it and let the user say yes; do not create it and report
+  back.
 - **`bots`** — it edits a live bot's name, bio, description, commands, profile photo
   and default admin rights. Those are the user's public-facing bots; the edits are
   theirs to make. Check `--help` for whether the installed build has it at all.

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/src/telegram_tools/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"

{telegram_tools-3.2.0 → telegram_tools-3.3.0}/src/telegram_tools/cli.py

@@ -4,6 +4,7 @@ import argparse
 import asyncio
 import json
 import sys
+from functools import partial
 from pathlib import Path
 from typing import Sequence
 
@@ -24,12 +25,14 @@ from telegram_tools.bots import (
 )
 from telegram_tools.client import create_client
 from telegram_tools.config import ConfigError, bot_id_from_token, load_config, lookup_bot_token, resolve_bot_token
+from telegram_tools.create import confirm_create, create_channel, create_group, create_topic, format_create_preview
 from telegram_tools.delete import confirm_clear_topic_messages, delete_topic_messages
 from telegram_tools.discovery import discover_chats, filter_chats, format_discovery_table
 from telegram_tools.doctor import run_doctor
 from telegram_tools.exporters import write_records
 from telegram_tools.resolver import EntityResolutionError, resolve_chat
 from telegram_tools.search import format_message_records, search_messages
+from telegram_tools.send import SendTarget, confirm_send, format_send_preview, require_send_allowed, send_message
 from telegram_tools.topics import get_forum_topics, get_forum_topics_by_ids
 
 
@@ -85,6 +88,35 @@ def build_parser() -> argparse.ArgumentParser:
     bots_parser.add_argument("--channel-rights", help=f"Default admin rights for channels, comma-separated, or none (needs a bot token). Valid names: {valid_rights}")
     bots_parser.add_argument("--yes", action="store_true", help="Skip the confirmation prompt")
 
+    send_parser = subparsers.add_parser("send", help="Send a message to a chat or forum topic")
+    send_parser.add_argument("--chat", required=True, help="Chat/channel username, link, or ID")
+    send_parser.add_argument("--topic", type=int, help="Topic ID to post into; omit for the chat itself")
+    send_parser.add_argument("--text", required=True, help="Message text, or - to read it from stdin")
+    send_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip the preview and send; the destination must be in TELEGRAM_SEND_ALLOWLIST",
+    )
+
+    create_parser = subparsers.add_parser("create", help="Create a group, channel, or forum topic")
+    create_kinds = create_parser.add_subparsers(dest="create_kind")
+
+    create_group_parser = create_kinds.add_parser("group", help="Create a supergroup, optionally with topics")
+    create_group_parser.add_argument("--title", required=True, help="Group name")
+    create_group_parser.add_argument("--about", help="Group description")
+    create_group_parser.add_argument("--forum", action="store_true", help="Enable topics on the new group")
+
+    create_channel_parser = create_kinds.add_parser("channel", help="Create a broadcast channel")
+    create_channel_parser.add_argument("--title", required=True, help="Channel name")
+    create_channel_parser.add_argument("--about", help="Channel description")
+
+    create_topic_parser = create_kinds.add_parser("topic", help="Create a topic in a forum group")
+    create_topic_parser.add_argument("--chat", required=True, help="Forum group username, link, or ID")
+    create_topic_parser.add_argument("--title", required=True, help="Topic name")
+
+    for kind_parser in (create_group_parser, create_channel_parser, create_topic_parser):
+        kind_parser.add_argument("--yes", action="store_true", help="Skip the confirmation prompt")
+
     subparsers.add_parser("doctor", help="Check local setup without printing secrets")
 
     return parser
@@ -154,6 +186,91 @@ async def _run_search(client, args) -> int:
     return 0
 
 
+def _entity_title(entity, fallback: str) -> str:
+    """A chat's name for the preview: a title, a person's name, or what was typed."""
+    title = getattr(entity, "title", None)
+    if title:
+        return str(title)
+    parts = [getattr(entity, "first_name", None), getattr(entity, "last_name", None)]
+    name = " ".join(part for part in parts if part)
+    return name or str(getattr(entity, "username", None) or fallback)
+
+
+def _message_text(raw: str) -> str:
+    # `-` is how a multi-line body gets in: quoting newlines through a shell flag is
+    # the kind of thing that silently sends half a message.
+    text = sys.stdin.read() if raw == "-" else raw
+    text = text.strip()
+    if not text:
+        raise ValueError("Nothing to send: the message text is empty.")
+    return text
+
+
+async def _run_send(client, args, config) -> int:
+    text = _message_text(args.text)
+    resolved = await resolve_chat(client, args.chat)
+    peer = resolved.input_entity
+
+    topic = None
+    if args.topic is not None:
+        topics = await get_forum_topics_by_ids(client, peer, [args.topic])
+        topic = topics[0] if topics else None
+
+    target = SendTarget(chat_id=resolved.id, chat_title=_entity_title(resolved.entity, args.chat), topic=topic)
+
+    confirm = None
+    if args.yes:
+        require_send_allowed(
+            config.send_allowlist,
+            chat_id=resolved.id,
+            username=getattr(resolved.entity, "username", None),
+            topic_id=args.topic,
+        )
+    else:
+        preview = format_send_preview(target, text, sender=_entity_title(await client.get_me(), "you"))
+        confirm = partial(confirm_send, preview)
+
+    result = await send_message(client, peer, target, text, confirm=confirm)
+    print(json.dumps(result.to_dict(), indent=2))
+    return 1 if result.cancelled else 0
+
+
+async def _run_create(client, args) -> int:
+    if args.create_kind is None:
+        raise ValueError("create needs one of: group, channel, topic.")
+
+    chat_title = None
+    peer = None
+    chat_id = None
+    if args.create_kind == "topic":
+        resolved = await resolve_chat(client, args.chat)
+        peer = resolved.input_entity
+        chat_id = resolved.id
+        chat_title = _entity_title(resolved.entity, args.chat)
+
+    forum = bool(getattr(args, "forum", False))
+    confirm = None
+    if not args.yes:
+        preview = format_create_preview(
+            args.create_kind,
+            args.title,
+            about=getattr(args, "about", None),
+            forum=forum,
+            chat_title=chat_title,
+        )
+        confirm = partial(confirm_create, preview)
+
+    if args.create_kind == "group":
+        created = await create_group(client, args.title, about=args.about, forum=forum, confirm=confirm)
+    elif args.create_kind == "channel":
+        created = await create_channel(client, args.title, about=args.about, confirm=confirm)
+    else:
+        created = await create_topic(client, peer, chat_id=chat_id, title=args.title, confirm=confirm)
+
+    print(json.dumps(created.to_dict(), indent=2))
+    return 1 if created.cancelled else 0
+
+
 EDIT_FLAGS = ("name", "bio", "description", "commands", "clear_commands", "photo", "remove_photo", "group_rights", "channel_rights")
 
 
@@ -224,7 +341,7 @@ async def _run_bots(client, args, config) -> int:
         return 0
 
     if not resolved.is_owned:
-        raise PermissionError(f"You do not own @{profile.username or profile.id}; only its owner can edit it.")
+        raise PermissionError(f"You do not own {f'@{profile.username}' if profile.username else f'bot {profile.id}'}; only its owner can edit it.")
 
     if "commands" in requested:
         requested["commands"] = parse_commands_file(requested["commands"])
@@ -294,6 +411,10 @@ async def run(args, *, client=None, config=None) -> int:
             return await _run_search(client, args)
         if args.command == "bots":
             return await _run_bots(client, args, config)
+        if args.command == "send":
+            return await _run_send(client, args, config)
+        if args.command == "create":
+            return await _run_create(client, args)
         raise ValueError(f"Unknown command: {args.command}")
     finally:
         if owns_client: