discord-cli-agent 0.1.0

Discord CLI for AI agents

discli

A command-line interface for Discord, built for AI agents and humans. Manage servers, send messages, react, handle DMs, threads, and monitor events — all from the terminal.

Install

pip install discord-cli-agent

For development:

pip install -e .

Requires Python 3.10+.

Setup

1. Create a bot at Discord Developer Portal
2. Enable all privileged intents (Presence, Server Members, Message Content)
3. Add the bot to your server with appropriate permissions
4. Configure your token:

# Option A: Save to config
discli config set token YOUR_BOT_TOKEN

# Option B: Environment variable
export DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN

# Option C: Pass directly
discli --token YOUR_BOT_TOKEN server list

Usage

Every command supports --json for machine-readable output.

Messages

discli message send #general "Hello world!"
discli message send #general "Check this out" --embed-title "News" --embed-desc "Big update"
discli message list #general --limit 20
discli message get #general 123456789
discli message reply #general 123456789 "Thanks for your question!"
discli message edit #general 123456789 "Updated text"
discli message delete #general 123456789

Direct Messages

discli dm send alice "Hey, need help?"
discli dm send 123456789 "Sent by user ID"
discli dm list alice --limit 10

Reactions

discli reaction add #general 123456789 👍
discli reaction remove #general 123456789 👍
discli reaction list #general 123456789

Channels

discli channel list --server "My Server"
discli channel create "My Server" new-channel --type text
discli channel create "My Server" voice-room --type voice
discli channel info #general
discli channel delete #old-channel

Threads

discli thread create #general 123456789 "Support Ticket"
discli thread list #general
discli thread send 987654321 "Following up on your issue"

Servers

discli server list
discli server info "My Server"

Roles

discli role list "My Server"
discli role create "My Server" Moderator --color ff0000
discli role assign "My Server" alice Moderator
discli role remove "My Server" alice Moderator
discli role delete "My Server" Moderator

Members

discli member list "My Server" --limit 100
discli member info "My Server" alice
discli member kick "My Server" alice --reason "Spam"
discli member ban "My Server" alice --reason "Repeated violations"
discli member unban "My Server" alice

Typing Indicator

discli typing #general                # 5 seconds (default)
discli typing #general --duration 10  # 10 seconds

Live Event Monitoring

# Listen to everything
discli listen

# Filter by server/channel
discli listen --server "My Server" --channel #general

# Filter by event type
discli listen --events messages,reactions

# Include bot messages (ignored by default)
discli listen --include-bots

# JSON output for piping to an agent
discli listen --json --events messages

Supported event types: messages, reactions, members, edits, deletes

Resolving Identifiers

All commands accept both IDs and names:

Type	By ID	By Name
Channel	123456789	#general
Server	123456789	My Server
Member	123456789	alice
Role	123456789	Moderator
Thread	123456789	Support Ticket
User (DM)	123456789	alice

JSON Output

Add --json to any command for machine-readable output:

$ discli message list #general --limit 1 --json
[
  {
    "id": "123456789",
    "author": "alice",
    "content": "Hello!",
    "timestamp": "2026-03-14T10:32:00+00:00"
  }
]

$ discli listen --json
{"event": "message", "server": "My Server", "channel": "general", "channel_id": "111", "author": "alice", "author_id": "222", "content": "hello", "message_id": "333", "mentions_bot": false, "attachments": [], ...}

Building an AI Agent

A basic agent loop using discli:

# 1. Listen for messages mentioning the bot
discli listen --json --events messages | while read -r event; do
  mentions_bot=$(echo "$event" | jq -r '.mentions_bot')
  if [ "$mentions_bot" = "true" ]; then
    channel_id=$(echo "$event" | jq -r '.channel_id')
    message_id=$(echo "$event" | jq -r '.message_id')
    content=$(echo "$event" | jq -r '.content')

    # 2. Show typing while thinking
    discli typing "$channel_id" --duration 3 &

    # 3. Generate response (your AI here)
    response="Got your message: $content"

    # 4. Reply to the message
    discli message reply "$channel_id" "$message_id" "$response"
  fi
done

Configuration

Config is stored at ~/.discli/config.json.

discli config set token YOUR_TOKEN
discli config show
discli config show --json

Token resolution order: --token flag > DISCORD_BOT_TOKEN env var > config file.

License

MIT