Skip to Content

Discord Bot

TL;DR

The Discord channel (pip install "cmdop-bot[discord]") uses discord.py to control CMDOP machines via slash commands. Create a bot at the Discord Developer Portal, set guild IDs for instant command sync, and run with DiscordBot(...).run(). Supports rich embeds, ephemeral messages, deferred responses, and PermissionManager integration.

Control your CMDOP machines from Discord with slash commands. Built on discord.py .

How do I set up a Discord bot?

  1. Create application at Discord Developer Portal 
  2. Create a bot and get the token
  3. Invite bot to your server with appropriate permissions

How do I install?

# Install cmdop-bot with Discord channel support (includes discord.py)
pip install "cmdop-bot[discord]"

How do I use the Discord bot?

# Import the Discord channel integration
from cmdop_bot.channels.discord import DiscordBot
 
# Create a Discord bot with guild-scoped slash commands
bot = DiscordBot(
    token="YOUR_DISCORD_BOT_TOKEN",   # Bot token from Discord Developer Portal
    cmdop_api_key="cmdop_xxx",        # Your CMDOP API key
    guild_ids=[123456789],            # Guild IDs for instant slash command sync
    machine="my-server",              # Default target machine hostname
)
 
# Start the bot (blocking call — runs the discord.py event loop)
bot.run()

What parameters are available?

ParameterTypeRequiredDescription
tokenstrYesDiscord bot token
cmdop_api_keystrYesCMDOP API key
guild_idslist[int]NoGuild IDs for faster slash command sync. None = global
allowed_userslist[int]NoAllowed Discord user IDs. None = allow all
permissionsPermissionManagerNoFine-grained permission control
machinestrNoDefault target machine hostname
modelstrNoAI model tier
timeoutfloatNoCommand timeout in seconds (default: 30.0)

What slash commands are supported?

CommandDescription
/helpShow available commands
/shell <command>Execute shell command
/exec <command>Alias for /shell
/agent <task>Run AI agent task
/ls [path]List directory (default: .)
/cat <path>Read file
/machine <hostname>Set target machine
/skills <action> [name] [prompt]List, show, or run skills
/skill <name> <prompt>Run a skill (shorthand)
/statusShow connection status

What features does the Discord bot have?

  • Slash commands via app_commands
  • Rich embeds for formatted output
  • Ephemeral messages for sensitive data
  • Deferred responses for slow operations
  • Guild-specific command sync (instant vs 1 hour global)

How do guild vs global commands work?

# Guild-specific: commands sync instantly, recommended for development and testing
bot = DiscordBot(
    token="...",
    cmdop_api_key="...",
    guild_ids=[123456789, 987654321],   # Specify one or more guild IDs
)
 
# Global: commands available in all servers, but takes up to 1 hour to sync
bot = DiscordBot(
    token="...",
    cmdop_api_key="...",
    # Omitting guild_ids registers commands globally across all servers
)

What environment variables are used?

# Discord bot token from the Developer Portal
export DISCORD_BOT_TOKEN="your-bot-token"
# CMDOP API key for authenticating with the backend
export CMDOP_API_KEY="cmdop_xxx"
# Default target machine hostname
export CMDOP_MACHINE="my-server"
# Guild ID for instant slash command sync (optional)
export DISCORD_GUILD_ID="123456789"

How do I add permissions?

from cmdop_bot.channels.discord import DiscordBot
from cmdop_bot import PermissionManager, PermissionLevel
 
# Create a permission manager for fine-grained access control
pm = PermissionManager()
# Grant full admin access to a specific Discord user
pm.add_admin("discord:123456789")
# Grant execute-only permission on a specific machine to another user
pm.grant("discord:555555555", machine="dev-server", level=PermissionLevel.EXECUTE)
 
# Pass the permission manager instead of allowed_users for granular control
bot = DiscordBot(
    token="YOUR_BOT_TOKEN",
    cmdop_api_key="cmdop_xxx",
    permissions=pm,             # Replaces simple allowed_users allowlist
)
 
bot.run()

What bot permissions are required?

When inviting the bot, ensure these permissions:

  • Send Messages
  • Use Slash Commands
  • Embed Links (for rich embeds)
Last updated on
Overview