Your First Bot

This guide walks you through creating a Discord application, inviting your bot to a server, and building a working agent that echoes messages — all from scratch. By the end, you will have a Python script that listens for Discord messages and replies automatically using discli serve.

Prerequisites

• discli installed
• A Discord account
• A Discord server where you have admin permissions (create a test server if needed)

Set up your Discord bot

discli config set token YOUR_BOT_TOKEN

Set token.

discli server list

My Test Server (ID: 1234567890123456789) — 5 members

Build your first agent

Now for the exciting part — building a bot that listens for messages and replies to them. This uses discli serve, which opens a persistent JSONL (JSON Lines) session over stdin/stdout.

import json
import subprocess

# Start discli in serve mode with JSON output
proc = subprocess.Popen(
    ["discli", "--json", "serve"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

# Read events from stdout, one JSON object per line
for line in proc.stdout:
    event = json.loads(line)

    # Only respond to non-bot messages
    if event.get("event") == "message" and not event.get("is_bot"):
        # Build a reply action
        cmd = json.dumps({
            "action": "reply",
            "channel_id": event["channel_id"],
            "message_id": event["message_id"],
            "content": f"You said: {event['content']}",
        })

        # Send the action to discli via stdin
        proc.stdin.write(cmd + "\n")
        proc.stdin.flush()

python my_bot.py

You: Hello bot!
My discli Bot: You said: Hello bot!

How the code works

Let’s break down each part of the agent:

Starting the serve process

proc = subprocess.Popen(
    ["discli", "--json", "serve"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

This launches discli serve as a subprocess. The --json flag tells discli to output events as JSON. The stdin and stdout pipes create a bidirectional communication channel:

• stdout — discli sends events (messages, reactions, member joins, etc.) as JSON lines
• stdin — your agent sends actions (send message, reply, react, etc.) as JSON lines

Reading events

for line in proc.stdout:
    event = json.loads(line)

Each line from stdout is a complete JSON object representing a Discord event. The event field tells you what happened. A message event looks like:

{
  "event": "message",
  "channel_id": "1111111111111111111",
  "message_id": "2222222222222222222",
  "author": "Alice",
  "author_id": "3333333333333333333",
  "content": "Hello bot!",
  "is_bot": false,
  "guild_id": "4444444444444444444"
}

Filtering events

if event.get("event") == "message" and not event.get("is_bot"):

This checks two things:

1. The event is a message (not a reaction, member join, etc.)
2. The message was not sent by a bot (prevents the bot from replying to itself in an infinite loop)

Sending actions

cmd = json.dumps({
    "action": "reply",
    "channel_id": event["channel_id"],
    "message_id": event["message_id"],
    "content": f"You said: {event['content']}",
})
proc.stdin.write(cmd + "\n")
proc.stdin.flush()

To make the bot do something, write a JSON action to stdin. The reply action sends a reply to a specific message. Other actions include send (send a new message), react (add a reaction), thread_create (create a thread), and many more.

The flush() call is important — without it, Python may buffer the write and the action will not reach discli immediately.

Troubleshooting

Extending your agent

Here are some ideas to build on top of this foundation:

• Add an AI model. Instead of echoing, send the message content to an LLM (Claude, GPT, etc.) and reply with the AI’s response.
• Read conversation history. Use the message_list action to fetch previous messages and give your AI context.
• Create threads. Use thread_create to start a dedicated thread for each conversation.
• Add slash commands. Register custom slash commands that users can invoke with /.
• Restrict permissions. Use discli permission set chat to limit what the agent can do.

What’s next