discord-cli
discord-cli is a headless, scriptable Discord CLI for automation and AI-agent workflows. It connects with a Discord bot token, runs a single command, and exits; command output is JSON by default so you can pipe it into jq, save it in CI logs, or call it from shell scripts and local agents.
Current release: 1.2.1 (PyPI)
Why discord-cli?
- Script Discord operations from shell, cron, GitHub Actions, or an AI agent
- Keep the bot token and workflow logic outside a long-running service process
- Use JSON output for automation and
jqfor filtering without custom glue code
Install
pip install discordcli-agents
# or
npx discordcli-agents
The installed command is discord-cli.
A man page ships with the package, so after a pip or pipx install you can read
the full reference offline:
man discord-cli
If your shell cannot find it (some virtualenv layouts are not on the default
MANPATH), point man at the file directly:
man "$(python -c 'import sysconfig; print(sysconfig.get_path("data"))')/share/man/man1/discord-cli.1"
Quick setup
- Create a bot at the Discord Developer Portal
- Add it to your server with the permissions you need
- Export a token:
export DISCORD_BOT_TOKEN="your-bot-token-here"
Or create a .env file in the same directory:
echo 'DISCORD_BOT_TOKEN=your-bot-token-here' > .env
Quick start
# Server info
discord-cli guild info
# List channels
discord-cli channel list
# Create a channel
discord-cli channel create "announcements" --type text --topic "Server announcements"
# Send a message
discord-cli message send 123456789012345678 --content "Hello from the CLI!"
# Export channel history
discord-cli export channel 123456789012345678 --limit 500 --format json > history.json
Recipes
Use the ready-to-copy examples in docs/recipes.md for:
- GitHub Actions notifications
- Scheduled maintenance and status checks
- Server/channel export and backup
- Bulk role and permission changes
- Claude/Codex and generic terminal-agent workflows
Need a deeper AI-agent workflow guide? See docs/ai-agents.md.
Command groups
channel— channel management and inspectionmessage— send, edit, react, purge, and fetch messagesguild— guild profile, emojis, stickers, bans, and prune flowsmember— list, info, kick, ban, timeout, nickname, and role checksrole— create, edit, assign, remove, and inspect rolespermissions— per-channel permission overwriteswebhook,threads,invite,category,search, andexport— the rest of the automation surface
Documentation
man discord-cli— the complete command reference, also readable in the repo at docs/man/discord-cli.1- Recipes
- AI agent integration
- Plugin guide
- Contributing guide
License
This project is licensed under the MIT License. See LICENSE for details.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file discordcli_agents-1.3.0.tar.gz.
File metadata
- Download URL: discordcli_agents-1.3.0.tar.gz
- Upload date:
- Size: 64.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3dd51d141bf2a11c10d28167c51624d112f70c922e49998d20d0773a65646301
|
|
| MD5 |
e87967d4400fbfbd31e9920238155ae0
|
|
| BLAKE2b-256 |
f8b15024f8112ba484a3d39e0ce8e35241ef812cb2ce6d23f3c5b745c763813f
|
Provenance
The following attestation bundles were made for discordcli_agents-1.3.0.tar.gz:
Publisher:
release.yml on 1solomonwakhungu/discord-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
discordcli_agents-1.3.0.tar.gz -
Subject digest:
3dd51d141bf2a11c10d28167c51624d112f70c922e49998d20d0773a65646301 - Sigstore transparency entry: 2603617515
- Sigstore integration time:
-
Permalink:
1solomonwakhungu/discord-cli@ca3ea10a5d06d34c5fb855707569e67188530808 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/1solomonwakhungu
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@ca3ea10a5d06d34c5fb855707569e67188530808 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file discordcli_agents-1.3.0-py3-none-any.whl.
File metadata
- Download URL: discordcli_agents-1.3.0-py3-none-any.whl
- Upload date:
- Size: 40.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
85938ba226b98cc8ff0cafb1bdb22c4dd2d406a6873bb94de7c7b4ce69c3717f
|
|
| MD5 |
15eb407e392c614e59a1c4b3f39ce5ce
|
|
| BLAKE2b-256 |
0017763e379884a10c6b612e6630b7a0d3c8fce8bb0134f201633fe711016fc0
|
Provenance
The following attestation bundles were made for discordcli_agents-1.3.0-py3-none-any.whl:
Publisher:
release.yml on 1solomonwakhungu/discord-cli
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
discordcli_agents-1.3.0-py3-none-any.whl -
Subject digest:
85938ba226b98cc8ff0cafb1bdb22c4dd2d406a6873bb94de7c7b4ce69c3717f - Sigstore transparency entry: 2603618273
- Sigstore integration time:
-
Permalink:
1solomonwakhungu/discord-cli@ca3ea10a5d06d34c5fb855707569e67188530808 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/1solomonwakhungu
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@ca3ea10a5d06d34c5fb855707569e67188530808 -
Trigger Event:
workflow_dispatch
-
Statement type:
