GitHub - famasya/discord-cli-agent

2 min read Original article ↗

A command-line tool to explore Discord channels, read messages, and send messages/forum posts through the Discord REST API.

Designed for AI Coding Agents: This CLI is optimized for agent workflows. By default, it emits JSON lines (metadata-friendly), and --markdown is available when you need human-readable summaries.

See AGENTS.md for contributor and integration guidance.

Features

  • Explore guild channels and threads (explore channels)
  • Read text channels, threads, and forum posts
  • Filter reads by content (--search) and date range (--since, --until)
  • Paginate filtered reads (--limit, --page)
  • Send messages with optional file attachments
  • Create forum posts with tags and archive duration
  • JSONL output by default, Markdown output with --markdown

Prerequisites

  • Go 1.23.2 or later
  • A Discord bot token with access to target guild/channels
  • Required bot permissions for the actions you run (read/send/thread access)

Installation

From Source

git clone https://github.com/abid/discord-cli-agent.git
cd discord-cli-agent
go build -o discord-cli-agent ./cmd/discord-cli-agent

Using Go Install

go install github.com/abid/discord-cli-agent/cmd/discord-cli-agent@latest

Configuration

You can provide credentials in two ways:

export DISCORD_BOT_TOKEN=...
export DISCORD_GUILD_ID=...

Or store token in an env file and pass it with --config:

discord-cli-agent --config ./.env ...

Note: --config currently loads DISCORD_BOT_TOKEN. DISCORD_GUILD_ID default is read from process environment or --guild-id.

Usage

Explore Channels

discord-cli-agent explore channels --guild-id <guild-id>
discord-cli-agent explore channels --type text --limit 50
discord-cli-agent explore channels --include-archived

Read Messages

discord-cli-agent read --channel-id <channel-id> --limit 20
discord-cli-agent read --channel-id <channel-id> --search "down" --since 2026-02-01 --until 2026-02-28
discord-cli-agent read --channel-id <channel-id> --search "incident" --limit 20 --page 2

Send Messages

discord-cli-agent send --channel-id <channel-id> --content "hello"
discord-cli-agent send --channel-id <channel-id> --file ./report.txt --content "see attachment"
discord-cli-agent send forum-post --channel-id <forum-id> --thread-name "Bug report" --content "details"

Output Formats

  • Default: JSONL (best for parsing and metadata pipelines)
  • Markdown: add --markdown

Example:

discord-cli-agent --markdown read --channel-id <channel-id> --limit 5

Troubleshooting

DISCORD_BOT_TOKEN is not set

Set DISCORD_BOT_TOKEN in environment, or provide --config <env-file>.

--guild-id is required (or set DISCORD_GUILD_ID)

Pass --guild-id, or export DISCORD_GUILD_ID before running explore channels.

failed to fetch channel / permission errors

Verify the bot can access that channel and has required Discord permissions.

Development

Project Structure

cmd/discord-cli-agent/main.go      # CLI entrypoint
internal/config/                   # Token/env parsing
internal/discord/                  # Commands + Discord API logic
internal/output/                   # JSONL/Markdown formatting
internal/errors/                   # Error and exit code mapping

Build and Test

go build ./...
go test ./...
go test -cover ./...

Security

  • Never commit bot tokens (.env is gitignored)
  • Redact IDs/tokens when sharing logs
  • Use least-privilege bot permissions for production guilds