CLI Reference

CLI Reference#

The bot entrypoint is telegram-acp-bot.

usage: telegram-acp-bot [-h] [-V] [--telegram-token TELEGRAM_TOKEN]                         [--agent-command AGENT_COMMAND]                         [--allowed-user-id ALLOWED_USER_ID]                         [--allowed-username ALLOWED_USERNAME]                         [--workspace WORKSPACE]                         [--permission-mode {ask,approve,deny}]                         [--permission-event-output {stdout,off}]                         [--acp-stdio-limit ACP_STDIO_LIMIT]                         [--acp-connect-timeout ACP_CONNECT_TIMEOUT]                         [--restart-command RESTART_COMMAND]                         [--log-format {text,json}]                         [-m {compact,normal,verbose}]                         [--scheduled-tasks-db SCHEDULED_TASKS_DB] command ... positional arguments: command register-commands   Register Telegram slash commands via the Bot API                         (setMyCommands). options: -h, --help            show this help message and exit -V, --version         show program's version number and exit --telegram-tokenTELEGRAM_TOKEN                         Telegram bot token --agent-commandAGENT_COMMAND                         ACP agent command line, e.g. 'codex-acp' or 'uv run                         examples/echo_agent.py'. --allowed-user-idALLOWED_USER_ID                         Allowed Telegram user ID. Can be repeated. --allowed-usernameALLOWED_USERNAME                         Allowed Telegram username (with or without @). Can be                         repeated. --workspaceWORKSPACE                         Default workspace path for /new when path is not                         provided. --permission-mode{ask,approve,deny}                         Default ACP permission mode. --permission-event-output{stdout,off}                         Where ACP permission/tool event logs are emitted. --acp-stdio-limitACP_STDIO_LIMIT                         Asyncio StreamReader limit in bytes for ACP stdio                         transport. --acp-connect-timeoutACP_CONNECT_TIMEOUT                         Timeout in seconds for ACP initialize/new_session                         handshake. --restart-commandRESTART_COMMAND                         Optional command used by /restart to relaunch the bot                         (e.g. 'uv run telegram-acp-bot'). --log-format{text,json}                         Application log format. -m, --activity-mode{compact,normal,verbose}                         Activity display mode. 'normal' (default) emits each                         activity event as its own message. 'compact' collapses                         all intermediate events into a single in-place status                         message that is replaced by the final answer when the                         agent responds. 'verbose' streams append-only updates                         for active reply and tool activity. --scheduled-tasks-dbSCHEDULED_TASKS_DB                         SQLite database path used for deferred scheduled                         follow-ups.

Arguments#

  • --telegram-token Default: TELEGRAM_BOT_TOKEN. Required if TELEGRAM_BOT_TOKEN is not set.

  • --agent-command Default: ACP_AGENT_COMMAND. Required if ACP_AGENT_COMMAND is not set.

  • --restart-command Default: ACP_RESTART_COMMAND. Optional command used by /restart to relaunch the process.

  • --allowed-user-id Repeatable allowlist of Telegram user IDs. At least one allowlist entry is required across IDs/usernames.

  • --allowed-username Repeatable allowlist of Telegram usernames. @ prefix is optional; values are normalized to lowercase. At least one allowlist entry is required across IDs/usernames.

  • --workspace Default workspace used by /new when no workspace path is provided.

  • --permission-mode Default: ACP_PERMISSION_MODE. Allowed values: ask, approve, deny.

  • --permission-event-output Default: ACP_PERMISSION_EVENT_OUTPUT. Allowed values: stdout, off.

  • --acp-stdio-limit Default: ACP_STDIO_LIMIT. Asyncio stdio reader limit in bytes.

  • --acp-connect-timeout Default: ACP_CONNECT_TIMEOUT. Timeout in seconds for ACP initialize + new_session handshake.

  • -m, --activity-mode Default: ACP_ACTIVITY_MODE. Allowed values: normal, compact, verbose. In normal, the bot sends activity/tool updates as separate messages without streaming edits. In compact, the bot keeps a single in-progress reply message per prompt, updates that message in place, and keeps the normal activity emoji in the message text while work is in progress. In verbose, the bot streams append-only updates in place for active reply text and tool activity, then finalizes the same message when possible.

  • -V, --version Print CLI version and exit.

Notes#

  • /restart behavior:

    • If ACP_RESTART_COMMAND (or --restart-command) is set, that command is executed.

    • Otherwise, the bot re-execs itself using sys.executable + sys.argv.

    • It requires an active session and reports session context (session_id, workspace) in the response.

    • /restart N [workspace] selects and loads a resumable session in-process (no process relaunch) and replies with a resume acknowledgment instead of a relaunch message.

  • Access control behavior:

  • MCP behavior:

    • telegram-acp-bot always advertises an internal MCP stdio server (telegram-channel) to the ACP agent.

register-commands#

Register (or delete) the bot’s slash commands in Telegram via setMyCommands.

telegram-acp-bot register-commands --telegram-token <TOKEN> [options]

Options#

  • --telegram-token Default: TELEGRAM_BOT_TOKEN. Required if TELEGRAM_BOT_TOKEN is not set.

  • --scope BotCommandScope to target. Allowed values: default, all_private_chats, all_group_chats, all_chat_administrators. Default: default (global scope for all users).

  • --language-code IETF language code for language-specific registration (e.g. en, es). Omit to register for all languages.

  • --dry-run Print the commands that would be registered without calling the Telegram API.

  • --delete Delete registered commands for the given scope/language instead of setting them (deleteMyCommands). Useful for cleanup flows.

Examples#

Register commands for all users (default scope):

telegram-acp-bot register-commands --telegram-token "$TELEGRAM_BOT_TOKEN"

Preview what would be registered without calling the API:

telegram-acp-bot register-commands --telegram-token "$TELEGRAM_BOT_TOKEN" --dry-run

Register commands only for private chats in English:

telegram-acp-bot register-commands \
  --telegram-token "$TELEGRAM_BOT_TOKEN" \
  --scope all_private_chats \
  --language-code en

Delete all registered commands for the default scope:

telegram-acp-bot register-commands --telegram-token "$TELEGRAM_BOT_TOKEN" --delete

Notes#

  • Command definitions are sourced from the codebase constant telegram_acp_bot.telegram.bot.BOT_COMMANDS. Running register-commands is idempotent — it is safe to call multiple times.

  • Exit code 0 on success; 1 on Telegram API error.