{"id":48758484,"url":"https://github.com/bytelandtechnology/telegram-agent-cli","last_synced_at":"2026-04-14T05:00:29.956Z","repository":{"id":349768285,"uuid":"1203688627","full_name":"ByteLandTechnology/telegram-agent-cli","owner":"ByteLandTechnology","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-13T02:42:08.000Z","size":238,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T04:29:19.158Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ByteLandTechnology.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T09:20:55.000Z","updated_at":"2026-04-13T02:42:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"d95e1876-58ef-490e-8cf3-4151f0278138","html_url":"https://github.com/ByteLandTechnology/telegram-agent-cli","commit_stats":null,"previous_names":["bytelandtechnology/telegram-agent-cli"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ByteLandTechnology/telegram-agent-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteLandTechnology%2Ftelegram-agent-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteLandTechnology%2Ftelegram-agent-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteLandTechnology%2Ftelegram-agent-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteLandTechnology%2Ftelegram-agent-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ByteLandTechnology","download_url":"https://codeload.github.com/ByteLandTechnology/telegram-agent-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ByteLandTechnology%2Ftelegram-agent-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31782740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-13T04:25:03.884Z","updated_at":"2026-04-14T05:00:29.949Z","avatar_url":"https://github.com/ByteLandTechnology.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telegram-agent-cli\n\nTelegram automation CLI for testing bots, running scenarios, and exposing\nTelegram operations as MCP tools for AI agents.\n\nStructured output in YAML (default), JSON, TOML, table, or NDJSON.\nEncrypted local storage. Interactive REPL. Managed daemon mode. Scenario runner.\n\n## Install\n\nFor skill/runtime usage, install the npm package so `telegram-agent-cli` is available\non `PATH`:\n\n```sh\nnpm install -g telegram-agent-cli\npnpm add -g telegram-agent-cli\nbun install -g telegram-agent-cli\ntelegram-agent-cli --help\n```\n\nIf you cannot do a global install, use a one-shot package execution fallback:\n\n```sh\nnpm exec --package=telegram-agent-cli -- telegram-agent-cli --help\npnpm dlx telegram-agent-cli --help\nbunx telegram-agent-cli --help\n```\n\nBuild from source only when developing locally:\n\n```sh\ncargo build --release\n./target/release/telegram-agent-cli --help\n```\n\nThe npm package now resolves a matching platform subpackage that already\ncontains the native binary for your machine. It does not download from GitHub\nReleases during install or first run. Supported npm targets:\n\n- `darwin-arm64`\n- `darwin-x64`\n- `linux-arm64`\n- `linux-x64`\n- `windows-arm64`\n- `windows-x64`\n\nIf your package manager skips optional dependencies, or if you install on an\nunsupported target, the wrapper package may install without a usable binary.\nReinstall with optional dependencies enabled, install the matching platform\npackage explicitly, or build from source with Cargo instead.\n\n## Releases\n\nGitHub Releases still publish versioned CLI archives and checksum files for\nsupported targets. In parallel, the npm release now publishes one main wrapper\npackage plus matching platform binary packages for supported targets:\n\n- `telegram-agent-cli`\n- `telegram-agent-cli-darwin-arm64`\n- `telegram-agent-cli-darwin-x64`\n- `telegram-agent-cli-linux-arm64`\n- `telegram-agent-cli-linux-x64`\n- `telegram-agent-cli-windows-arm64`\n- `telegram-agent-cli-windows-x64`\n\nWindows release artifacts now use the GNU LLVM target triples\n`x86_64-pc-windows-gnullvm` and `aarch64-pc-windows-gnullvm`, so local Windows\ninstall helpers and release evidence align with the packaged npm binaries.\n\nCI now treats `semantic-release` as the single release orchestrator and the\nsingle release pipeline. On pushes to `main`, the `Release` workflow runs on a\nmacOS runner, installs the cross-build toolchains once, and lets\n`semantic-release` drive the rest of the flow. During the semantic-release\n`prepare` phase it stamps the next version, builds all supported platform\nbinaries, and stages `dist/` plus `dist/npm`. During `publish` it writes\n`release-evidence.json`, verifies the package set, publishes the GitHub Release\nassets, publishes all platform npm packages, and finally publishes the root npm\npackage that references them through `optionalDependencies`.\n\nThe npm publish step is fixed to GitHub Actions Trusted Publisher (OIDC) in the\nrelease workflow. It relies on GitHub-hosted runners plus `id-token: write`,\ndoes not require `NPM_TOKEN`, and bootstraps npm CLI `11.5.1+` only for the\nlive `npm publish` calls instead of replacing the runner's bundled npm.\n\nOnce Trusted Publisher is verified for every package, npm recommends restricting\npackage settings to \"Require two-factor authentication and disallow tokens\" and\nrevoking old automation tokens.\n\nFor npm publication rehearsal, stamp a version and build the staged package set\nfirst, then run:\n\n```sh\nnode ./npm/prepare-release.cjs \u003cversion\u003e\nnpm run release:build-all -- --version \u003cversion\u003e\nnpm run release:npm:verify -- --version \u003cversion\u003e --git-tag v\u003cversion\u003e --staged-dist ./dist/npm\nnpm run release:npm:dry-run -- --version \u003cversion\u003e --git-tag v\u003cversion\u003e --staged-dist ./dist/npm\n```\n\nThese commands keep the root package, platform packages, optional dependency\nversions, and staged artifacts aligned before any live npm publish happens.\n\nFor manual artifact-only rehearsals, use the `Build Artifacts` workflow\ndispatch and provide the version explicitly. It reuses the same cross-build and\nstaging script as the formal `Release` workflow on `main`.\n\nThe repository remains the source of truth for the skill itself. The final\nshipped skill contract is the bare `telegram-agent-cli` command, while local\ndevelopment may use `cargo run -- ...` and built-binary verification may use\n`./target/release/telegram-agent-cli ...`.\n\nFor clone-first release installs, use a released checkout and the repo-native\ninstall helper:\n\n```sh\ngit clone https://github.com/ByteLandTechnology/telegram-agent-cli.git\ncd telegram-agent-cli\ngit checkout v\u003cversion\u003e\n./scripts/install-current-release.sh \u003cversion\u003e\n```\n\nEach release should keep the Git tag, GitHub Release page, binary archives,\nchecksum files, `release-evidence.json`, and `.release-manifest.json` aligned\nto the same version.\n\n## Quick Start\n\n```sh\n# Register a bot account\ntelegram-agent-cli account add-bot --name mybot --token-env BOT_TOKEN\n\n# Authenticate\ntelegram-agent-cli account login mybot --qr\n\n# Send a message\ntelegram-agent-cli send --as mybot --to @user --text \"hello\"\n\n# Open an interactive session\ntelegram-agent-cli repl --as mybot --chat @user\n\n# Start MCP server for AI agents\ntelegram-agent-cli mcp\n```\n\n## Output Format\n\nAll commands support `--format`:\n\n```sh\ntelegram-agent-cli paths                                    # YAML (default)\ntelegram-agent-cli paths --format json                      # JSON\ntelegram-agent-cli paths --format toml                      # TOML\ntelegram-agent-cli message follow --as mybot --chat @user --format ndjson  # NDJSON stream\n```\n\nStructured results use a `ResultEnvelope` with `command`, `status`, `summary`,\n`data`, `next_steps`, and `errors`. Sensitive fields are redacted automatically.\n\nWhen you use the managed daemon lifecycle, daemon metadata is stored at\n`state_dir/daemon/server.json` and daemon logs are written to\n`state_dir/daemon/server.log`.\n\n## Account Management\n\n```sh\ntelegram-agent-cli account add-user --name alice --api-id 12345 --api-hash \u003chash\u003e\ntelegram-agent-cli account add-bot --name mybot --token-env BOT_TOKEN\ntelegram-agent-cli account login alice --qr\ntelegram-agent-cli account login alice --code-env TELEGRAM_CLI_LOGIN_CODE --password-env TELEGRAM_CLI_2FA_PASSWORD\ntelegram-agent-cli account list\ntelegram-agent-cli account use mybot        # set default\ntelegram-agent-cli account logout mybot\n```\n\nSwitch accounts per-invocation with `--as`:\n\n```sh\ntelegram-agent-cli send --as alice --to @user --text \"hello\"\ntelegram-agent-cli send --as mybot --to @user --text \"hello\"\n```\n\nInspect the current context:\n\n```sh\ntelegram-agent-cli context show\ntelegram-agent-cli context show --as mybot\n```\n\n## Messaging\n\n```sh\ntelegram-agent-cli send --as mybot --to @user --text \"hello\"\ntelegram-agent-cli send-file --as mybot --to @user report.pdf --caption \"Q1 report\"\ntelegram-agent-cli send-photo --as mybot --to @user screenshot.png\n\n# With inline/reply keyboards\ntelegram-agent-cli send --as mybot --to @user --text \"Choose:\" \\\n  --inline-keyboard '[[\"Yes:callback:yes\",\"No:callback:no\"]]'\n```\n\n### Reading Messages\n\n```sh\ntelegram-agent-cli message recv --as mybot --chat @user --limit 20\ntelegram-agent-cli message recv --as mybot --chat @user --unread-only\ntelegram-agent-cli message unread --as mybot --chat @user\n```\n\n### Waiting \u0026 Streaming\n\n```sh\n# Block until a matching message arrives\ntelegram-agent-cli wait --as mybot --chat @user --text-contains Welcome --timeout 5s\n\n# Stream matching messages (NDJSON recommended)\ntelegram-agent-cli message follow --as mybot --chat @user --format ndjson \\\n  --text-contains response --limit 5 --timeout 30s\n```\n\n### Bot Interaction\n\n```sh\n# Discover buttons and actions\ntelegram-agent-cli message list-actions --as mybot --chat @user\n\n# Click an inline button\ntelegram-agent-cli message click-button --as mybot --chat @user Start --wait-timeout 5s\n\n# Trigger a discovered action\ntelegram-agent-cli message trigger-action --as mybot --chat @user \\\n  bot-command:my_bot:start --wait-timeout 5s\n```\n\n### Other Message Operations\n\n```sh\ntelegram-agent-cli message forward --as mybot --from @src --to @dst --message-ids 42,43\ntelegram-agent-cli message edit --as mybot --chat @user --message-id 42 --text \"updated\"\ntelegram-agent-cli message pin --as mybot --chat @user --message-id 42\ntelegram-agent-cli message unpin --as mybot --chat @user --message-id 42\ntelegram-agent-cli message download --as mybot --chat @user --message-id 42 --output file.jpg\n```\n\n## Bot Configuration\n\n```sh\ntelegram-agent-cli bot set-commands --as mybot \\\n  --commands '/start|Start the bot,/help|Show help'\n\ntelegram-agent-cli bot set-info --as mybot \\\n  --description \"A helpful bot\" --about \"v1.0\"\n```\n\n## Peers \u0026 Aliases\n\n```sh\ntelegram-agent-cli peer resolve --as mybot @user\ntelegram-agent-cli alias set --as mybot qa-bot qa_bot\ntelegram-agent-cli alias list\ntelegram-agent-cli list contacts --as mybot\ntelegram-agent-cli list chats --as mybot\n```\n\n## Scenario Automation\n\nDefine test scenarios in YAML and replay them:\n\n```sh\ntelegram-agent-cli run scenarios/echo.yaml\ntelegram-agent-cli export --run-id latest\ntelegram-agent-cli export --run-id latest --format ndjson\n```\n\n## REPL\n\nInteractive session with a chat. History, tab completion, and plain-text\noutput for readability:\n\n```sh\ntelegram-agent-cli repl --as mybot --chat @user\n```\n\nREPL commands: `/send`, `/recv`, `/wait`, `/actions`, `/click`, `/trigger`,\n`/unread`, `/help`, `/exit`.\n\n## MCP Server\n\nExpose Telegram operations as tools for AI agents over stdio:\n\n```sh\ntelegram-agent-cli mcp\n```\n\nConfigure in Claude Desktop or other MCP clients:\n\n```json\n{ \"command\": \"telegram-agent-cli\", \"args\": [\"mcp\"] }\n```\n\n## Daemon Mode\n\nRun the same JSON-RPC/MCP tool surface as a managed background daemon:\n\n```sh\ntelegram-agent-cli daemon start\ntelegram-agent-cli daemon status --format json\ntelegram-agent-cli daemon stop\n```\n\nThe daemon binds a local loopback TCP endpoint, records its runtime metadata\nunder the telegram-agent-cli state directory, and preserves the shared managed\ncontract: `daemon start`, `daemon stop`, `daemon restart`, and\n`daemon status`. Foreground attached execution remains out of scope; use\n`telegram-agent-cli mcp` when you want a stdio-bound server in the current\nterminal.\n\n## Diagnostics\n\n```sh\ntelegram-agent-cli paths                    # runtime directories\ntelegram-agent-cli doctor                   # full diagnostic check\ntelegram-agent-cli doctor --format json     # machine-readable\n```\n\n## Help\n\n```sh\ntelegram-agent-cli --help                   # plain text\ntelegram-agent-cli help send                # structured (YAML)\ntelegram-agent-cli help send --format json  # structured (JSON)\n```\n\n## Development\n\n```sh\ncargo test\ncargo clippy -- -D warnings\ncargo fmt --check\n```\n\nRun locally without a release build:\n\n```sh\ncargo run -- send --as mybot --to @user --text \"hello\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytelandtechnology%2Ftelegram-agent-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytelandtechnology%2Ftelegram-agent-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytelandtechnology%2Ftelegram-agent-cli/lists"}