Skip to main content

​
Overview

The run command executes arbitrary shell commands on the machine hosting the bot. This is an extremely powerful administrative tool that provides direct system access.
DANGER: This command can execute ANY system command with the bot’s permissions.This command:
  • Can modify or delete files on the host system
  • Can expose sensitive information
  • Can crash or compromise the bot
  • Should NEVER be made available to regular users
  • Should be used with extreme caution even by bot owners

​
Command Signature

/run <command>

​
Parameters

​
command
String
required
The shell command to execute on the host machine

​
Permissions Required

OWNERS ONLY - This command can only be executed by bot owners as defined in the bot’s configuration.This is the highest permission level available and is NOT based on Discord permissions.

​
Usage Examples

​
Check system uptime

/run uptime
Response: 
[Embed]
Title: Output
Stdout: 
 14:23:45 up 5 days, 2:15, 1 user, load average: 0.15, 0.12, 0.08

Stderr:

​
List files in the current directory

/run ls -la

​
Check disk usage

/run df -h

​
View bot process information

/run ps aux | grep bot

​
Implementation Details

Source reference: src/commands/administration.rs:73-112

​
Execution Method

The command executes using tokio::process::Command with the following structure: 
tokio::process::Command::new("sh")
    .arg("-c")
    .arg(command)
    .output()
    .await
This means:
  • Commands are executed through the sh shell
  • Shell features like pipes (|), redirects (>, >>), and environment variables ($VAR) work
  • The command runs with the same user permissions as the bot process

​
Output Format

The command returns an embed with two fields:
  1. Stdout - Standard output from the command
  2. Stderr - Standard error output from the command
Both outputs are formatted in code blocks for readability.

​
Command Deferral

The command defers the response before execution (ctx.defer_or_broadcast()) to prevent timeout errors for long-running commands.

​
Security Considerations

Critical Security Warnings:
  1. Access Control: Never share bot owner credentials or grant this permission to untrusted users
  2. Command Validation: There is NO validation or sanitization of input commands - any valid shell command will execute
  3. Destructive Operations: Commands like rm -rf, shutdown, or reboot will execute without confirmation
  4. Information Disclosure: Commands can read sensitive files (config files, environment variables, database credentials)
  5. Resource Exhaustion: Commands can consume system resources (CPU, memory, disk I/O)
  6. Network Operations: Commands can make network requests, download files, or expose the bot to attacks

​
Safe Usage Practices

  1. Always verify the command before executing
  2. Use read-only commands when possible (ls, cat, grep)
  3. Avoid wildcards in destructive operations
  4. Test commands in a development environment first
  5. Monitor output for unexpected results
  6. Keep logs of all executed commands
  7. Limit bot process permissions on the host system

​
Use Cases

  • Checking bot system health and resource usage
  • Viewing log files without SSH access
  • Performing emergency maintenance operations
  • Debugging system-level issues
  • Monitoring bot process status
Consider using more specific, restricted commands for routine operations instead of this general-purpose command.

​
Alternatives to Consider

For routine operations, consider implementing specific commands instead:
  • System status → Create a dedicated /status command
  • Log viewing → Create a /logs command with specific file access
  • Process management → Create specific /restart or /reload commands
These alternatives provide:
  • Better input validation
  • Restricted operation scope
  • Clearer audit trails
  • Reduced security risk

Build docs developers (and LLMs) love

Get started for freeTalk to us