Serve Protocol

discli serve implements a bidirectional communication protocol over stdin and stdout using newline-delimited JSON (JSONL). Each line is a single, self-contained JSON object. Events flow out on stdout; actions flow in on stdin.

flowchart LR
    subgraph Agent Process
        A[AI Agent / Script]
    end
    subgraph discli serve
        B[Event Handlers] --> C[stdout]
        D[stdin] --> E[Action Dispatcher]
    end
    subgraph Discord
        F[Discord Gateway]
    end

    F -- events --> B
    C -- JSONL events --> A
    A -- JSONL actions --> D
    E -- API calls --> F

Protocol basics

• Transport: stdin (actions) and stdout (events), one JSON object per line
• Encoding: UTF-8
• Delimiter: newline (\n) — each line is a complete JSON object
• Direction: stdout is server-to-client (events), stdin is client-to-server (actions)
• Correlation: actions can include a req_id field; the corresponding response will echo it back

Events (stdout)

Events are emitted by discli as things happen on Discord. Every event object has an "event" field identifying its type.

Lifecycle events

Message events

Interaction events

Reaction events

Member events

Response events

Every action sent via stdin produces a response on stdout:

Example event payloads

{
  "event": "message",
  "server": "My Server",
  "server_id": "111111111111111111",
  "channel": "general",
  "channel_id": "222222222222222222",
  "author": "Alice#1234",
  "author_id": "333333333333333333",
  "is_bot": false,
  "content": "Hello bot!",
  "timestamp": "2026-03-15T10:30:00+00:00",
  "message_id": "444444444444444444",
  "mentions_bot": true,
  "is_dm": false,
  "attachments": [],
  "reply_to": null
}

{
  "event": "slash_command",
  "command": "ask",
  "args": {"question": "What is discli?"},
  "channel_id": "222222222222222222",
  "user": "Alice#1234",
  "user_id": "333333333333333333",
  "guild_id": "111111111111111111",
  "interaction_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "is_admin": false
}

{
  "event": "response",
  "req_id": "msg-001",
  "ok": true,
  "message_id": "555555555555555555"
}

Actions (stdin)

Actions are JSON objects sent to discli via stdin. Every action must have an "action" field. Optionally include "req_id" to correlate the response.

{"action": "send", "channel_id": "222222222222222222", "content": "Hello!", "req_id": "msg-001"}

Messaging

Streaming

Streaming lets you progressively update a single message, similar to how ChatGPT streams responses. Content is buffered and flushed to Discord every 1.5 seconds to respect rate limits.

Streaming example

{"action": "stream_start", "channel_id": "222222222222222222", "req_id": "s1"}

{"event": "response", "req_id": "s1", "stream_id": "a1b2c3d4", "message_id": "555555555555555555"}

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "Here is the "}

{"action": "stream_chunk", "stream_id": "a1b2c3d4", "content": "answer to your question..."}

{"action": "stream_end", "stream_id": "a1b2c3d4", "req_id": "s1-end"}

Interactions

Typing

Presence

status can be online, idle, dnd, or invisible. activity_type can be playing, watching, listening, or competing.

Reactions

Threads

Polls

answers is an array of strings or objects with text and optional emoji fields. Minimum 2 answers required.

Channels

Members

Roles

DMs

Message queries

Server

Request-response correlation

Every action can include a req_id field (any string). The response will echo it back, letting you match responses to requests in concurrent scenarios.

{"action": "send", "channel_id": "123", "content": "Hello", "req_id": "abc-001"}

{"event": "response", "req_id": "abc-001", "ok": true, "message_id": "456"}

Error handling

When an action fails, the response includes "error" instead of "ok":

{"event": "response", "req_id": "abc-002", "error": "Channel not found: 999"}

Common error conditions:

Non-fatal errors (e.g., slash command sync failures) are emitted as standalone error events:

{"event": "error", "message": "Failed to sync commands to My Server: ..."}

Event filtering

Use command-line options to filter which events are forwarded:

# Only message and reaction events
discli serve --events messages,reactions

# Only events from a specific server
discli serve --server "My Server"

# Only events from a specific channel
discli serve --channel "#general"

# Exclude bot's own messages
discli serve --no-include-self

Available event filter values: messages, reactions, members, edits, deletes.

Slash command registration

Pass a JSON file to register slash commands on startup:

discli serve --slash-commands commands.json

[
  {
    "name": "ask",
    "description": "Ask the bot a question",
    "params": [
      {"name": "question", "type": "string", "required": true, "description": "Your question"}
    ]
  },
  {
    "name": "status",
    "description": "Check bot status"
  }
]

Commands are synced per-guild for instant availability. When a user invokes a slash command, a slash_command event is emitted with an interaction_token that you use to respond.

Next steps