Manage a Discord server via CLI scripts in commands/. 18 stateless commands (read, write, destructive) that connect, execute, and disconnect. All output is JSON. Pass --help to any command for usage info.
Prerequisites
Bot token in .env must be valid and the bot must be in the server with Manage Channels, Manage Roles, and Send Messages permissions.
Available Commands
All commands are run as:
node commands/<command>.mjs <args>
Read Operations (safe, no side effects)
| Command | Usage | Purpose |
|---|---|---|
server-info.mjs |
node commands/server-info.mjs |
Server overview: members, channels, roles, boost level |
list-channels.mjs |
node commands/list-channels.mjs |
All channels grouped by category with topics |
list-members.mjs |
node commands/list-members.mjs |
All human members with roles and join dates |
read-messages.mjs |
node commands/read-messages.mjs <channel> [--limit N] |
Read recent messages (default 10, max 100) |
list-roles.mjs |
node commands/list-roles.mjs |
All roles with name, color, member count, hoisted status |
list-threads.mjs |
node commands/list-threads.mjs <channel> |
Active threads in a channel |
Write Operations (create content, non-destructive)
| Command | Usage | Purpose |
|---|---|---|
send-message.mjs |
node commands/send-message.mjs <channel> <message> |
Send a message to any channel |
send-embed.mjs |
node commands/send-embed.mjs <channel> --title "..." --description "..." [--field "Name|Value"] [--color #hex] [--footer "..."] |
Send a rich branded embed |
edit-message.mjs |
node commands/edit-message.mjs <channel> <message-id> <new-content> |
Edit a bot message |
create-channel.mjs |
node commands/create-channel.mjs <category> <name> [--topic "..."] [--read-only] |
Create a text channel under a category |
create-thread.mjs |
node commands/create-thread.mjs <channel> <thread-name> [--message-id ID] |
Create a thread, optionally from a message |
set-topic.mjs |
node commands/set-topic.mjs <channel> <topic> |
Update a channel's topic |
create-role.mjs |
node commands/create-role.mjs <name> [--color #hex] [--hoist] |
Create a new role |
assign-role.mjs |
node commands/assign-role.mjs <username> <role-name> |
Assign an existing role to a member |
remove-role.mjs |
node commands/remove-role.mjs <username> <role-name> |
Remove a role from a member |
pin-message.mjs |
node commands/pin-message.mjs <channel> <message-id> |
Pin a message in a channel |
Destructive Operations (require --confirm flag)
These commands will not execute without the --confirm flag. Always ask the user for explicit confirmation before running destructive operations.
| Command | Usage | Purpose |
|---|---|---|
delete-channel.mjs |
node commands/delete-channel.mjs <channel> --confirm |
Delete a channel permanently |
delete-role.mjs |
node commands/delete-role.mjs <role-name> --confirm |
Delete a role permanently |
Output Format
All commands return JSON to stdout. Successful operations include { "ok": true, ... }. Errors include { "error": "description" }. Parse the output to confirm success before reporting to the user.
Common Workflows
Post an announcement:
node commands/send-message.mjs announcements "New release is live. Check the changelog."
Send a branded embed:
node commands/send-embed.mjs announcements --title "UPDATE" --description "New features deployed." --field "Status|Live"
Read recent messages:
node commands/read-messages.mjs general --limit 20
Assign a role to a member:
node commands/assign-role.mjs "username" "Admin"
Create a discussion thread:
node commands/create-thread.mjs chat "Weekly Discussion"
Add a new channel:
node commands/create-channel.mjs GENERAL "off-topic" --topic "Anything goes"
Check server health:
node commands/server-info.mjs