Repository navigation
Releases
v0.15.0
0.15.0 - 2026-10-20
Review-remediation slice: validators, cores, dry-run planners, and docs brought back into agreement. All machine-API changes are additive (new JSON keys on existing rows only); no renamed keys, removed commands, or exit-code changes.
Hardening slice: eight deliberate exposures tightened. Machine shapes stay additive (new optional flags and JSON keys only), but new fail-closed acks may turn previously-accepted invocations into exit 1 with guidance — the sanctioned posture-ack exception in the Stability rule.
Added
- Additive enrichment on forwarded and album message rows (
poll/todoobjects and full peer identity withusername, matching read-path rows). - Additive dry-run preview fields:
noforwardson chat-settings previews,notifyon pin previews. "via": "import"outcome on phone-target contact adds resolved through contact import.- Posture acks:
--allow-rawontele raw(allow_raw:trueover serve/MCP, including dry-run previews);--allow-insecure-app-dirforTELE_APP_DIRoutside per-user paths;--allow-trace(TELE_ALLOW_TRACE=1) forTELE_LOG=trace. --redact-phonesoncontact list,profile get(overrides--show-phone), andtakeout export(redactscontacts.json); matchingredact_phonesparams on the serve/MCP ops.- MCP
--groupsscoping extended to resources (tele://profileneeds groupprofile,tele://dialogsneeds groupdialog;tele://skillstays public). - Short service codes (3–6 digits) redacted in code/OTP contexts; FTS5 update trigger keeping the message-cache index in sync on UPDATE.
- Docs: supply-chain pin-review cadence (
docs/security.md), offline measurement baselines and budget protocol (docs/perf-baselines.md), scope ADR-009. - Root
SECURITY.md(reporting route and threat-model pointer), adocs/README.mddocumentation index,.editorconfig, GitHub issue forms, a pull-request template, andCODEOWNERS.CONTRIBUTING.mdmoved to the repository root, where GitHub renders it. npm/package.jsonnow declareshomepageandbugs.
Changed
- Usage-error coverage: non-positive message ids, empty search queries and topic titles, conflicting pin show/all with id, and blank kick/admin user targets now fail locally with exit 1 in both the CLI and machine-API lanes.
- Fail-closed posture:
.envpermission-tightening failure aborts startup instead of warning;--phone/--change-phoneon argv rejected under--no-inputfor prompting flows (non-prompting staged steps keep warn-only behavior). - Docs resynced with the implementation: 93 routed ops (96
ops.listentries), 35 read-only, 9 destructive ops includingraw, registry 25; noforwards behavior rewritten; posture acks (--allow-raw,--allow-insecure-app-dir,--allow-trace),--redact-phones, and MCP resource--groupsscoping documented; contract gate now parses escaped pipes and asserts exact flag and registry counts. - Dry-run truthfulness: chat-settings previews include
noforwards;account sessionsdry-runs are fully offlinewouldpreviews; pin/typing/click previews validate before rendering;--fieldsnow projectslistenstreaming rows instead of being silently ignored. chat statson basic groups, badtopic listchat targets, and topic close/reopen/delete with--unpinnow fail as usage errors.- Every repository URL in the project pointed at
github.com/QMahyar/tele-cli, which does not exist; the published npm package and the README release and CI badges linked to that dead location.Cargo.toml,npm/package.json, the CLI help footer, the README, and the docs now point atgithub.com/mahyartdb/tele-cli. - The GitHub repository is public and carries a description, topics, secret scanning with push protection, Dependabot security updates, and private vulnerability reporting.
.gitignoreis grouped by purpose and covers Rust output, credentials and sessions, release and npm artifacts, agent scratch, editors, OS cruft, logs, and coverage..gitattributesnormalizes every text file to LF.
Fixed
- Admin-log
--untilno longer burns--limiton out-of-window events; invite and membership-request listings page with real cursors, dedup, and page caps. - CLI and machine-API default agreement on kick/ban, promote rights (including story and rank rights), and Saved-Messages delete with
--revoke. - Session lifecycle: logout/delete close before removing files and report removal failure; exports checkpoint before snapshot; staged-login failures leave no phantom pending state; expired codes stay distinct from invalid codes across datacenter migration.
- Secret and file hygiene: pending auth material created private atomically; credential cache keyed on content hash; short numbers stay redacted; passwords held in zeroizing wrappers.
- Cache sync acquires rate budget per page; message-cache writes are transactional; serve dedupe keys on update-sourced pts; oversized serve frames and duplicate request ids rejected explicitly;
--count 0emits zero rows. - CI could not clone the repository. The workflow declared
permissions: {}, which strips every permission fromGITHUB_TOKEN, soactions/checkoutfailed withfatal: repository not foundon all five jobs and the suite had been red since it was added. The workflow now grantscontents: read. - Two
doctortests failed on Linux only.session_checkreports ok just when the session file is owner-only, and the fixtures were created with the default umask, sodoctorcorrectly reported "world-accessible" and the assertions failed. The fixtures now set mode 0600, matching a real session file. - The published npm package shipped no README and no LICENSE, so npm rendered
ERROR: No README data found!on the package page. The release job now stages both into the package root.
v0.14.0
Released 2026-09-18.
The glow-up release: output/UX upgrades, the full rival-library ship list, perf and security hardening, and approved new dependencies. All machine-API changes are additive (new commands, flags, and JSON keys only); no renamed keys, removed commands, or exit-code changes, so the CLI contract is intact and this ships as MINOR per the Stability rule.
Added
- Output and UX upgrades - global
--fieldsprojection for machine output (comma-separated dotted fields, requires--json/--jsonl, unknown fields are usage errors); global--no-inputfailing closed on any prompt; bug-report path (issue URL in help text, error output, and a stderr footer); local-onlydoctorhealth check; credentialwizardover the config and env writers;completions manroff man pages rendered withclap_mangen. - Poll coverage -
msg poll-closeplusmsg poll-resultswith voters and unread readers. - Story coverage -
story editplusviews,viewers,reactions, andlinkexport. msg send --effect- animated message-effect id on text, single-file, and checklist sends.- Checklist create -
msg send --todowith repeatable--todo-item(plus--todo-others-can-append/--todo-others-can-complete), withtodorow rendering (media_kind: "todo"). - Translate and transcribe wraps -
msg translate(by--textor--chatwith--ids),msg transcribefor voice/video-note messages, andmsg transcribe-ratefor rating a transcription. - Silent forward - forward messages silently via raw
ForwardMessages. - Topic icons - topic
--emojiaccepts a single-codepoint emoji (resolved to a custom-emoji document id via emoji search) or a custom-emoji document id directly. - New ops are routed through serve/MCP with dry-run
wouldpayloads like the rest of the surface.
Changed
- Perf wins - O(1) replay dedupe (
CappedMapsequence numbers, was an O(10k) scan); single-pass UTF-16 text split (14.6x);HashSet-based privacy merge and deletion dedupe (4x); incremental takeout peer map with a sized line buffer. - Hardening -
tele raw --argsJSON bounded at 1 MiB; std-only secret hygiene for credentials and SRP key material;cargo-denypolicy plus secret-scan CI. - Approved dependencies -
secrecy0.10SecretStringcredential wrap,zeroize1.9 SRP transient wipe,clap_mangen0.3 man pages. - Typing and startup -
ProxyType/BudgetLane/PrivacyKey/ContactState/UsageCtxboundary types;mainreturnsExitCodewith a shared clap-error path; typedLogLevelplus a raw stdout printer; machine--jsonenvelopes forskillandcompletions,--dry-runforskill install; takeout progress gated on TTY stderr as well as human mode.
Fixed
- Exact
--countstop, retained--untildeadline, and parked closed serve channels;SAFETYnotes on all unsafe blocks andMaybeUninitfor termios; shared error-message markers plus anInvocationErrorextension trait andsource()wiring;app_data_dir_checkedpropagation through owned call sites; language-nit batch (poll-mode usage errors, graceful envelopes, derives,must_use, param shapes, stack consts, phone-nonce invariant); envelope/TTY/color/precedence contract docs.
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.14.0Or build from source: cargo build --release.
v0.13.0
Released 2026-09-13.
Changed
msg scheduleddates are RFC 3339 strings - thedatefield in scheduled-message rows was a raw Unix-epoch integer, the only machine-API date not using the sharedmessage_to_jsonRFC 3339 format; it is now a string like every other date row. Type change (int → string) is breaking for parsers that expected an integer; documented indocs/cli-contract.md(msg scheduled) per ADR-003's change policy.
Fixed
- 26 verified bugs from a 10-lens adversarial audit, each with an offline regression test:
msg exportjoins the documented no-budget lanes and its scan is bounded (server cap without date filters, skip budget with them);account delete/passwordinteractive guard counts resolved accounts instead of CLI flags; session hardening (IPv6-only Telethon imports rejected, export copies through a temp file so failures never destroy the destination, lock file unlinked only after guard drop); credentials overlay skips non-UTF-8 env vars and--helpworks without HOME/APPDATA;msg send --splitapplies--reply/--scheduleto the first chunk only and--thumbnail/--media-ttlnow take effect (grammers builder order); serve retries queue-full/hello/parse-error replies with a deadline, caps reconnects at the documented 5, and bounds all inline reply loops;dialog list --foldervalidates 0/1 on the CLI path and Folder-marker rows no longer break the GetDialogs cursor anchor;msg export truncatedno longer false-positives at the cap;listen --untilinvalid values exit with usage instead of panicking;parse_target/classify_targetagree on+-prefixed targets; completions normalize npm platform-suffixed binary names; serve/MCPchat settingsappliesnoforwards,chat statsrejects user peers,chat kick --bankeeps the ban when--rightsomitsview_messages; forum-topic collection terminates on Deleted-only pages;profile set --username removeclears the username per contract; privacy merge emits explicit per-peer rules before categorical base rules;messages.Searchfilter rejects non-string JSON;tele rawhuman mode renders the payload;takeout startdeletes previous export artifacts only after the new session is accepted; staged login persists pending state before the code request;cache statshonors--dry-run.
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.13.0Or build from source: cargo build --release.
v0.12.0
Released 2026-09-08.
Full audit ship: six new capabilities, a release supply chain (SBOM + build provenance), and roughly forty fixes from the five-domain adversarial audit (kernel, commands, streams, security, release engineering). Every done capability row is contract-tested against the real CLI surface.
Added
msg export- per-chat history export:tele msg export --account A --chat X [--format txt|jsonl] [--out FILE] [--limit N] [--offset-id M] [--since T] [--until T]. One message JSON object per line (default) or a human transcript;--outfiles are created with private permissions and sensitive basenames are refused; channel rows carry an additivelinkt.me permalink (https://t.me/<user>/<id>orhttps://t.me/c/<internal>/<id>); rows carrycount/scanned/truncatedwhen writing to a file. Also routed as a serve/MCPmsg exportop (Read lane, unbounded like download).msg get --replied- with a single--id, fetches the message the target replies to via grammers'get_reply_to_message(resolves cross-chat discussion parents for channel-post comments) and embeds it as an additivereplied_toobject. Rejected for--idsbatches; absent when there is no parent. Serve/MCP:GetParams.replied.profile photos- profile photo history viaiter_profile_photos:tele profile photos [--user USER] [--limit N]. Rows carry{id, date, size, sizes[], current}(photos.getUserPhotos for users, chat-photos sweep for channels/supergroups). Serve/MCP:profile photosop.chat permissions- participant rights read-back:tele chat permissions --chat X --user U. Full admin-rights flag map (12 write-side flags), full banned-rights map (22 flags +until_dateas RFC 3339), creator rights, plusrank/can_edit/kicked_by/promoted_bywhere provided; basic groups degrade to the participant role with an explanatory note. Serve/MCP:chat permissionsop.msg send --file -- streamed stdin uploads viaupload_stream:--file-size <BYTES>(exact stdin byte count) and--file-name <NAME>required; same 2 GiB cap; cannot be combined with other--filepaths or albums;--file-size/--file-nameare rejected when no stdin upload is present.- MCP resources -
tele mcpnow advertises the MCPresourcescapability with three read-only context resources:tele://skill(the embedded SKILL.md, same bytes astele skill print),tele://profile(bound account profile as JSON), andtele://dialogs(first 100 dialogs as JSON). Available in full and--read-onlymodes; unknown URIs fail with a clean-32602listing the valid set. - Release supply chain - every release target ships an SPDX SBOM (anchore/sbom-action) and a build-provenance attestation (actions/attest-build-provenance); both actions are SHA-pinned and the token scope is limited to the build job.
docs/release.mddocumentsgh attestation verifyand corrects the manual npm-publish fallback to reproduce the CI staging (publishing from the barenpm/directory would ship a launcher that can never find a binary). - Skill versioning - the installed
SKILL.mdcompatibility line is stamped from the binary version andtele skill installwarns when an existing install predates the running binary; a contract test pins the stamp toCargo.tomlso it cannot drift again.
Fixed
Kernel and executor
- FTS5 message cache:
INSERT OR REPLACEno longer silently bypasses the sync triggers -PRAGMA recursive_triggers = ONat open, with anfts5vocab/integrity-checkregression test that fails without it. - Token bucket: idle time no longer banks credit - the refill anchor advances while the bucket is full and refills are bounded by the remaining room, so a long idle gap cannot mint an instant full refill or keep over-minting afterwards.
- Replay dedupe (
CappedMap): re-delivered updates refresh their eviction position, so a redelivered update is no longer re-emitted as new when its original entry rotates out. - Peer eviction set is bounded (1024, clear-on-full) instead of permanent and unbounded.
+phonetargets now require at least 5 digits (including country code):+1can no longer trigger a realcontacts.ImportContactsside effect; parenthesized/dotted phone spellings classify consistently betweenparse_targetandclassify_target.- Per-account fan-out:
msg download,msg export,story send, andtakeout exportrun without the 300s per-account budget (matching the documented serve lane table - the old cap killed legitimate mid-transfer work and reported exit 3), and timed-out account tasks are aborted instead of left running. - Proxy URLs: IPv6 hosts are bracket-wrapped (
socks5://[::1]:9050) instead of producing a malformed authority. --tagwarns on tagged accounts that have no session file yet instead of skipping them silently.config.tomlwrites fsync the temp file before rename (no zero-length config on crash); the missing-HOME panic prints an actionable, scrubbed message on stderr.- Session import: stale
-wal/-shmsidecars of the previous database are deleted before the rename (a hot WAL from a crashed run would be replayed onto the imported session), and the account lock now covers only the copy+probe+install window instead of the whole source read. - Cache open: directory creation and permission hardening run via
spawn_blockinginstead of blocking the async runtime.
Messaging
msg deletereports the server's real affected count (partialwhen some ids were not deleted) instead of fabricating"deleted": N.msg download --allresume no longer permanently skips the checkpoint boundary: two-bound checkpoints (last_message_id+max_seen_id), local-timezone--since/--untildate handling, and an additivetruncatedflag.msg get --idsbatch fetch (single-RPC chunks of 100, additivemissing_ids).msg search --from meuses the server-side own-messages filter.msg send --split Nchunks oversized text into sequential UTF-16-aware messages (paragraph-preferred cuts).listen --count Nand--until <ts>finite-stream exits (combined across accounts, stderr notice, exit 0).listen: the connect semaphore no longer starves accounts at--parallel 1; gap detection uses the incomingpts_count(grammers continuity rule) and gap/peer state now survives reconnects; stream task panics surface their payload; filter applicability is consistent and documented (direction/pattern filters suppress action-family rows instead of silently bypassing them).chat settings --noforwardsactually works:messages.toggleNoForwardsexists at layer 227 and is now wired (the old rejection claimed the layer lacked it).admin-log --untilrejects post-2038 timestamps instead of silently wrapping viaas i32and disabling pagination early-stop;--sinceis now counted against the limit inside collection so it can no longer hide matching events.
Chats and contacts
chat createno longer reports failure after server-side success onUpdates::Combinedresponses (the retry path duplicated chats).contact addno longer reports first-time adds as failures (min-usercontact:falseresponse is a warning).--signaturesno longer clears author profiles (writessignature_profilestoo).chat requests:--userwith--linkis rejected instead of silently ignoring the link scope.chat kick:--banno longer overrides an explicit--rights view_messagesvalue;--demoterejects--preset/--rights(they were silently discarded); empty--rightsis rejected instead of promoting nobody.- Bare invite hashes are canonicalized to full
https://t.me/+...URLs where the API expects a link (--edit/--importers), while--checkstill extracts the hash. dialog --folderpagination anchors per-page and album bundling no longer drops entries.dialog folder-createverifies the written filter afterUpdateDialogFilter(a racing creator overwriting the id now surfaces an honest error) and counts Chatlist folders when allocating ids.dialog draftsdocs pinned to the exact channel-id form (the-100Bot-API convention, matching numeric--chat).
Accounts, privacy, and security
- Login: inverted
session_existed_beforefixed (failed logins deleted good sessions) across the code and staged paths. - Staged login:
--stage resend/--stage cancel-code, 303 DC migration on sign-in/resend/cancel and change-phone flows (auto home-DC switch + one retry), 2FA accepts piped stdin like the code step, takeout start clears stale export artifacts. account deletepurges session, pending secrets, and config entry after server-side delete;--dry-runis reachable without--yes.privacy set --replace(revocation) added; merge mode rejects a user resolved on both the allow and deny sides (alias-proof: username vs numeric id of the same person).phone --confirm-codedry-run redacts the OTP code andphone_code_hash; one-time secrets on argv (--confirm-code/--phone-hash) warn about process listings like--phonedoes;--show-tokenbypasses the log scrubber so the promised login URI actually prints in quiet mode.account sessions --terminatedry-run applies the same current-session guard as the real run instead of promising a refused action.- Upload exfiltration guard blocks
.session.export/.session.tmp;export-sessionrefuses a hard link to the live session (file-identity comparison). - Callback button
data_strdecodes lossy UTF-8 (invalid bytes become U+FFFD) instead of an empty string, consistent with listen rows and the click selector. rand_seedmixes a process-wide call counter: same-tick topic creations no longer collide onrandom_id.
Streams and serving
stream.resyncnow arms on every StreamError (auto-catch-up after a broken stream) and completion guards use bounded retries, so a saturated driver cannot silently drop final envelopes (10s drain budget docum...
v0.11.3
Released 2026-09-04.
Fixed
dialog folder-create: the 12-char title cap and peer-requirement validation now also apply on the CLI path (previously only serve/MCP enforced them).
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.11.3Or build from source: cargo build --release.
v0.11.2
Released 2026-09-04.
Fixed
dialog folder-create: titles over 12 characters are rejected offline naming the Telegram cap, instead of the server's misleadingMESSAGE_TOO_LONG.- Pinned the embedded
skill.mdasset to LF in.gitattributessoinclude_str!output matches the contract tests on Windows CRLF checkouts (pre-existing CI failure on main).
Note
- npm 0.11.1 was published from an intermediate commit and lacks only the folder-title offline validation; 0.11.2 supersedes it.
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.11.2Or build from source: cargo build --release.
v0.11.1
Released 2026-09-04.
Fixed
cache search: hyphenated queries no longer crash with a raw SQLite error; user queries are escaped as FTS5 phrases (LIVE-TESTno longer parses as column syntax).cache sync:media_kindnow stores clean labels (document,photo, …) matchingmsg get, instead of the Rust Debug format.msg send --schedule: relative durations (90s,30m,24h,7d,2w, and+-prefixed variants) are now accepted, matchingchat invite --expire; negative durations are rejected.dialog folder-create: new--include-chat/--pin-chat/--exclude-chatflags; rule-only folders with no peers are rejected offline with a clear error instead of the server's obscureMESSAGE_TOO_LONG.- RPC errors
PREMIUM_ACCOUNT_REQUIREDandMESSAGE_TOO_LONGnow carry a short plain-language hint appended to the message;codeandnameare unchanged. dialog folder-create: titles over 12 characters are rejected offline naming the Telegram cap, instead of the server's misleadingMESSAGE_TOO_LONG.
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.11.1Or build from source: cargo build --release.
v0.11.0
Released 2026-09-04.
Added
tele dialog folders/folder-create/folder-delete/folder-reorder: list, create, delete, and reorder chat folders (dialog filters) viamessages.{getDialogFilters,updateDialogFilter,updateDialogFiltersOrder}.tele msg scheduled/scheduled-delete/scheduled-send: list scheduled messages (messages.getScheduledHistory), delete them, or send them immediately.tele cache sync/search/stats/clear: per-account local SQLite message cache ({app}/cache/{name}.cache.db) with FTS5 full-text search for offline queries.- Serve/MCP surface grows 67 → 78 routed ops (
cachegroup + 4 dialog folder ops + 3 msg scheduled ops).
Fixed
docs/getting-started.md: npm install command now matches the published@qmahyar/teleclipackage name.docs/CONTRIBUTING.md: removed the stale hardcoded test count.docs/examples.md: added MCP/Cursor setup,tele serveembedding recipe, agent skill, local cache, folders, and scheduled-message recipes.README.md: added the Changelog to the documentation table.
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.11.0Or build from source: cargo build --release.
v0.10.0
Released 2026-09-02.
Changed
- Renamed the command from
teleclitoteleend to end: cargo builds bothteleand ateleclialias; the npm package installsteleas the primary bin withteleclikept as a deprecated alias for one transition cycle; release archives, bundled binaries, and the npm launcher now usetelenames; help text, completions, README, and docs all saytele. - App data directory renamed from
~/.config/telecli/%APPDATA%\teleclito~/.config/tele/%APPDATA%\tele.telemigrates an existing legacyteleclidata directory automatically on first run (one-time rename; aTELE_APP_DIRoverride skips migration).
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.10.0Or build from source: cargo build --release.
v0.9.0
Released 2026-09-02.
Added
tele skillprints an embedded SKILL.md (Agent Skills spec: frontmatter, normative usage rules, 16-group command map, JSON envelope, recipes) to stdout — an agent loads it into context in one command.tele skill install [--dir PATH] [--force]writes the skill totele/SKILL.mdunder detected agent skill directories (.claude/skills,.config/opencode/skills,.cursor/skills) or a custom dir; overwrites are refused without--force; nothing detected and no--diris a usage error.- README now leads with install and quick start; new "For agents" section covering
tele skilland MCP.
Changed
- README rewritten as a concise front door (482 → 180 lines): command tables replaced by
tele --helppointers, every count verified (16 groups, 67 MCP tools, 25 raw methods, 13 build targets); stale session-report artifacts (SHIPPED.md,implementation-summary.md) removed. docs/getting-started.md: removed the falsecargo install tele-cliinstruction (the crate is not on crates.io).
Binaries for this version were not published to GitHub. Install the matching build from npm:
npm install -g @qmahyar/telecli@0.9.0Or build from source: cargo build --release.