# Show HN: Discord-CLI – a headless Discord CLI that prints JSON and exits

> Source: <https://github.com/1solomonwakhungu/discord-cli>
> Published: 2026-10-27 14:03:55+00:00

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.4.0 ([PyPI](https://pypi.org/project/discordcli-agents/))

- 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 `jq` for filtering without custom glue code

```
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:

``` python
man "$(python -c 'import sysconfig; print(sysconfig.get_path("data"))')/share/man/man1/discord-cli.1"
```

Install the repository's `discord-cli-server-management` skill with the open skills CLI:

```
npx skills add 1solomonwakhungu/discord-cli --skill discord-cli-server-management
```

The skill is listed on
[skills.sh](https://skills.sh/1solomonwakhungu/discord-cli/discord-cli-server-management) and works with Codex,
Claude Code, Cursor, GitHub Copilot, and other agents supported by the skills CLI.

1. Create a bot at the [Discord Developer Portal](https://discord.com/developers/applications)
2. Add it to your server with the permissions you need
3. 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
# 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
```

Use the ready-to-copy examples in [docs/recipes.md](https://github.com/1solomonwakhungu/discord-cli/blob/main/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](https://github.com/1solomonwakhungu/discord-cli/blob/main/docs/ai-agents.md).

- `channel` — channel management and inspection
- `message` — send, edit, react, purge, and fetch messages
- `guild` — guild profile, emojis, stickers, bans, and prune flows
- `member` — list, info, kick, ban, timeout, nickname, and role checks
- `role` — create, edit, assign, remove, and inspect roles
- `permissions` — per-channel permission overwrites
- `webhook` ,`threads` ,`invite` ,`category` ,`search` , and`export` — the rest of the automation surface

- `man discord-cli` — the complete command reference, also readable in the repo at[docs/man/discord-cli.1](https://github.com/1solomonwakhungu/discord-cli/blob/main/docs/man/discord-cli.1)
- [Recipes](https://github.com/1solomonwakhungu/discord-cli/blob/main/docs/recipes.md)
- [AI agent integration](https://github.com/1solomonwakhungu/discord-cli/blob/main/docs/ai-agents.md)
- [Plugin guide](https://github.com/1solomonwakhungu/discord-cli/blob/main/docs/plugins.md)
- [Contributing guide](https://github.com/1solomonwakhungu/discord-cli/blob/main/CONTRIBUTING.md)

This project is licensed under the MIT License. See [LICENSE](https://github.com/1solomonwakhungu/discord-cli/blob/main/LICENSE) for details.