discord-tools

A local CLI for operating your Discord bot: discover server/channel/thread IDs, search and export messages, send messages, create channels and threads, clear messages, and manage the bot's settings — with a guided setup that walks you through the Discord Developer Portal (the BotFather it never had).

Sibling of telegram-tools: same menu for humans, same subcommands for agents, same safety gates on anything destructive. Bot-token auth only — no self-bots, ever (Discord ToS).

Install

pip install discord-tools-cli
discord-tools auth      # guided bot setup: portal walkthrough, token check, invite URL
discord-tools doctor    # verify token, message-content intent, servers, permissions

(The PyPI name is discord-tools-cli — plain discord-tools is squatted by an unrelated, archived package. The installed command is discord-tools.)

Python 3.11+. Bare discord-tools opens a looping menu for humans; agents and scripts pass a subcommand.

Commands

Profiles: a bot per agent

Tokens live in ~/.discord-tools/.env (mode 0600) as named profiles:

DISCORD_BOT_TOKENS=default:token-a,dobby:token-b

--profile dobby (before the subcommand) selects one; DISCORD_TOOLS_PROFILE sets the default; DISCORD_TOKEN overrides everything. auth writes this file for you — run it once per bot.

DISCORD_SEND_ALLOWLIST is a comma-separated list of channel/thread IDs that send --yes may post to. Unset means every unattended send is refused — each destination is opted in by hand.

Exports stay out of your repos

Relative --output names land in ~/.discord-tools/exports/, never the working directory. Message text coming back empty on every message means the message-content intent is off in the portal — doctor names it and auth walks you through enabling it.

For agents

skill/SKILL.md is a bundled agent skill describing the CLI surface and the rules an agent must follow (never clear-messages, allowlist-gated sends, never print tokens). It updates in the same commit as any CLI-surface change.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest    # no network, no real token

MIT. See SPEC.md for the v1 contract and CHANGELOG.md for history.