Discord CLI

discord-api is a JSON-first CLI over the Discord REST API v10. It is not an official Discord product. The commands are generated from Discord's official OpenAPI spec (discord/discord-api-spec, 246 operations). Each command's --help links the matching section of the docs.

Run locally

cd api-apps/discord-api
npm install --workspaces=false
bun run build
node dist/index.js --help

Authentication

Use a bot token: Developer Portal → your application → Bot → Reset Token. The CLI sends it as Authorization: Bot <token>.

<secret-manager-command> | discord-api auth --token-stdin            # bot token
<secret-manager-command> | discord-api auth --token-stdin --bearer   # OAuth2 user access token

You can also set DISCORD_BOT_TOKEN (or DISCORD_ACCESS_TOKEN for an OAuth2 bearer token). Environment variables win over the saved file, which is ~/.config/discord-api/credentials.json (0600).

A bot only sees servers it has been added to. A server admin has to open this link once:

https://discord.com/oauth2/authorize?client_id=<application_id>&scope=bot&permissions=<bits>

To read message text, enable Message Content Intent under Bot. To list members, enable Server Members Intent. Webhook token routes (webhooks execute-webhook <id> <token>) need no credentials.

Coverage

Commands are <first path segment> <operationId>, for example channels create-message, guilds list-guild-members or users list-my-guilds. Path params are positional arguments in URL order.

Bodies are JSON only. Multipart file uploads are not supported. The Gateway (websocket events) is not wrapped.

--all on list endpoints pages with after=<largest snowflake>, from the oldest item onward. Rate limits (HTTP 429) are reported with retry_after and are never retried automatically.

Examples

discord-api whoami
discord-api users list-my-guilds
discord-api guilds list-guild-channels <guild_id>
discord-api channels create-message <channel_id> --data '{"content":"Hello"}' --yes
discord-api channels list-messages <channel_id> --limit 50
discord-api channels list-messages <channel_id> --all
discord-api channels add-my-message-reaction <channel_id> <message_id> 👍 --yes
discord-api channels delete-message <channel_id> <message_id> --yes
discord-api guilds create-guild-channel <guild_id> --data '{"name":"support","type":0}' --yes
discord-api guilds list-guild-members <guild_id> --all
discord-api guilds add-guild-member-role <guild_id> <user_id> <role_id> --yes
discord-api webhooks execute-webhook <webhook_id> <webhook_token> --wait true --data '{"content":"hi"}' --yes
discord-api api GET /guilds/<guild_id>/roles

Development

python3 scripts/generate.py   # refresh src/endpoints.json from the official spec and docs
bun test
bun run test:node