One-shot REST commands unnecessarily open Gateway sessions and require privileged intents

[doggy8088]

Summary

A one-shot command that only needs the Discord REST API currently opens a Gateway connection and requests every intent, including all privileged intents.

I encountered this while trying to inspect the reactions on one known message:

export DISCORD_BOT_TOKEN="<valid bot token>"
uv run discli reaction list <channel_id> <message_id>

The channel ID and message ID were valid, and the token authenticated successfully. However, the command failed before it attempted to fetch the message because the application did not have every privileged Gateway intent enabled.

Environment

• macOS
• discord-cli-agent==0.9.1
• Python 3.12
• discord.py>=2.7.1
• discli run from the repository with uv run
• The same bot token was already being used by a separate, long-running bot process with its own Gateway session

Actual behavior

The command fails with:

discord.errors.PrivilegedIntentsRequired:
Shard ID None is requesting privileged intents that have not been
explicitly enabled in the developer portal.

The traceback points to run_action(), where discli constructs a client with all intents and starts a Gateway connection:

intents = discord.Intents.all()
client = discord.Client(intents=intents)
...
await client.start(token)

Source:

• src/discli/client.py
• src/discli/commands/reaction.py

The reaction command itself only does the following after the Gateway becomes ready:

ch = resolve_channel(client, channel)
msg = await ch.fetch_message(int(message_id))
reactions = [
    {"emoji": str(reaction.emoji), "count": reaction.count}
    for reaction in msg.reactions
]

The message is never fetched because Discord rejects the unnecessary Gateway IDENTIFY first. The failed startup also prints an Unclosed connector warning because the client is not closed when client.start() fails before on_ready.

Expected behavior

reaction list should use the REST API without opening a Gateway WebSocket.

Fetching one known message is supported by:

GET /channels/{channel.id}/messages/{message.id}
Authorization: Bot <token>

For a guild channel, Discord documents VIEW_CHANNEL and READ_MESSAGE_HISTORY as the required permissions. Reading the message's reaction summary does not require Presence, Server Members, Message Content, or reaction event intents.

The command should therefore work when:

• the bot token is valid;
• the bot can view the channel; and
• the bot has permission to read message history.

It should not require users to enable unrelated privileged intents.

Analysis

The behavior appears to come from using one shared Gateway-based runner for both one-shot REST commands and long-running event consumers.

discord.Client.start() performs login and then connects to the Gateway. Because the runner uses discord.Intents.all(), every invocation sends an IDENTIFY requesting GUILD_PRESENCES, GUILD_MEMBERS, and MESSAGE_CONTENT, even if the command only performs an HTTP request.

This has several consequences:

1. REST-only commands fail unless unrelated privileged intents are enabled.
2. Users are encouraged to grant sensitive access that the requested operation does not need.
3. Every CLI invocation creates an unnecessary short-lived Gateway connection and IDENTIFY attempt.
4. This adds avoidable session-start pressure for applications that already have a long-running Gateway bot.
5. Discord's Gateway documentation limits clients to 1,000 IDENTIFY calls per 24 hours across the application; reaching that limit terminates active sessions and resets the bot token.
6. Resource resolution currently uses cache-only methods such as client.get_channel(), which unnecessarily couples otherwise REST-capable commands to Gateway-populated state.

This is broader than reaction list: other one-shot commands using the same run_discord() path also open a Gateway session before performing REST operations.

Suggested direction

A reasonable separation would be:

• Use an HTTP-only lifecycle for one-shot commands: authenticate with Client.login(), resolve resources with REST fetch methods such as fetch_channel(), perform the action, and close the client in finally.
• Reserve Client.start() and Gateway sessions for commands that actually consume real-time events or voice state, such as listen, serve, and voice functionality.
• For Gateway commands, request only the intents required by the selected features instead of Intents.all().
• Handle PrivilegedIntentsRequired explicitly and always close the client on startup failures.

References

• Discord Gateway documentation: connections, intents, and Identify limits
• Discord Message resource: Get Channel Message permissions
• Discord API authentication
• discord.py Client.start()
• discord.py Client.login()

[DevRohit06]

Thank you for the report. The analysis is accurate and the references are appreciated, it made this straightforward to verify.

Some context on why it works this way currently, since it wasn't an oversight so much as a decision that didn't age well. discli started as the serve command, a persistent bot that genuinely needs a Gateway connection and most intents. The one-shot commands were added afterwards and inherited that same runner rather than being designed with their own lifecycle. Sharing one client configuration kept things simple at the time and avoided per-command intent bookkeeping.

The other reason was resolution ergonomics. A Gateway connection populates the cache, which is what allows discli message send #general "text" or discli member info myserver someuser to work without the user hunting for snowflake IDs. On a REST-only path those name lookups cost an API call per guild instead of being free. For a CLI aimed at humans and agents that was worth something. What I underweighted is that it's a poor trade when the cost is requiring three privileged intents for an operation that needs none, and when ID-based lookups, which are the common case for agents, get penalised for a convenience they don't use.

On scope, I audited the run_discord() call sites and it extends beyond reaction list. Fifteen modules use that path, and only voice requires a Gateway session, since it depends on guild.voice_client. The interact commands appear to need one but do not; they send a message with components and exit. serve and listen construct their own clients and are legitimate event consumers, though they also request Intents.all() unnecessarily.

The direction matches your suggestion:

1. run_discord() defaults to a REST-only lifecycle via login(), with gateway=True as an explicit opt-in used only by voice.
2. Feature-scoped intents for serve and listen in place of Intents.all().
3. Resolvers become async and read cache-first with a REST fallback, so they work correctly under both lifecycles. The duplicated resolve_member, resolve_role and resolve_user helpers currently spread across command modules get consolidated into utils.py.
4. Explicit handling for PrivilegedIntentsRequired, and closing the client in a finally block to resolve the unclosed connector warning.

Two consequences worth stating up front. Name-based resolution will be slower on the REST path for the reason above, while ID-based resolution improves across the board. And resolving a member by username will still require the Server Members intent, since the REST list-members endpoint enforces it. That case will raise a clear error directing the user to enable the intent or supply an ID, rather than the current misleading "not found".

The resolvers have no test coverage at present, so this needs tests against a faked client before it ships.

If this is something you'd like to work on, I'd be happy to review a PR and can point you at the call sites. Otherwise I'll pick it up.

[doggy8088]

@DevRohit06 I have already submitted a pull request here: #25