Skip to content

Using Umbra

Jump to bottom
Rocco A edited this page Sep 9, 2026 · 1 revision

Using Umbra

Umbra has two control surfaces:

  • The GUI is the desktop application included in packaged releases.
  • The TUI is a responsive terminal application available from a source checkout.

Both interfaces edit the same config/config.jsonc when run from the source tree. Avoid running both at the same time against the same Discord application. Your token is stored locally as plain text; never share the configuration file or include the token in screenshots, logs, or issue reports.

Desktop GUI

Launch it

Download the correct Windows or Linux build from the latest release and open Umbra. Choose the artifact matching your architecture (x86_64 or ARM64). Packaged builds create config/config.jsonc beside the executable on first use.

From a source checkout, use:

git clone https://github.com/Umbra-Development/Discord-Raid-External-Bot.git
cd Discord-Raid-External-Bot
uv sync
uv run gui

Configure and start the bot

  1. Open General and enter the application token.
  2. Set the command prefix and positive whole-number cooldown values.
  3. Open Messages and edit the Standard and Notification templates. Each template is limited to 2,000 characters and has a live Discord-style preview.
  4. Select Save settings. Reload discards unsaved form changes and reads the configuration from disk again.
  5. Select Start bot. Starting also validates and saves the current form. The button changes to Stop bot while the child process is running.
  6. Open Console to watch live output. Follow output controls automatic scrolling, while Clear console clears the visible history. The complete process log remains in config/bot.log.

Closing the GUI stops its bot process.

GUI tabs and shortcuts

  • General: token, prefix, and cooldown settings.
  • Messages: templates, character counts, and message preview.
  • Console: live bot output and connection state.
  • About: configuration location and shortcut reminder.
Shortcut Action
Ctrl+S / Cmd+S Save settings
Ctrl++ / Cmd++ Increase interface scale
Ctrl+- / Cmd+- Decrease interface scale
Ctrl+0 / Cmd+0 Reset interface scale to 100%
Ctrl / Cmd + mouse wheel Adjust interface scale
Ctrl+L / Cmd+L Clear the visible console

The toolbar also provides appearance, interface-scale, and preview-scale menus. Scroll with the mouse wheel or trackpad even when a scrollbar is hidden.

Terminal UI

Launch it

The 0.0.4 packaged executable launches the GUI. To use the TUI, run it from a source checkout in a terminal:

git clone https://github.com/Umbra-Development/Discord-Raid-External-Bot.git
cd Discord-Raid-External-Bot
uv sync
uv run cli

The TUI loads config/config.jsonc and attempts to start the bot immediately. If the configuration has no valid token, it stays open and shows the problem; enter the settings in Config, save them, and start the bot again.

Layout and navigation

In a wide terminal, the active Console or Config view appears beside the always-visible Controls panel. Below 80 columns, Umbra switches to separate Console, Config, and Controls tabs. You can use the mouse, keyboard navigation, or the numbered view shortcuts.

  • Console: colored live application and Discord output.
  • Config: token, prefix, cooldowns, and both 2,000-character message templates.
  • Controls: connection status, bot lifecycle, config reload, console following, log clearing, and quit.

Save config validates the form and writes it to disk. Reload from disk replaces unsaved form values. Reload config refreshes the running bot's configuration without replacing the values currently being edited in the form.

TUI shortcuts

Key Action
s Start bot
x Stop bot
r Restart bot
l Reload the active configuration
f Toggle automatic console following
Ctrl+L Clear the console
1 Show Console
2 Show Config
3 Show Controls in a narrow terminal
Ctrl+S Save the configuration form
Ctrl+P Open the command palette; choose Change theme
q Stop the bot and quit

The footer displays the main key bindings. Umbra is the default theme; the Change theme command also offers Textual's built-in themes.

Troubleshooting

  • If authentication fails, verify that the token belongs to the intended Discord application and has not been reset.
  • If commands do not appear, check the Console for login, synchronization, or permission errors.
  • If the terminal layout feels cramped, widen it to at least 80 columns or use 1, 2, and 3 to switch views.
  • If a config value is rejected, ensure the prefix is not empty, cooldowns are positive whole numbers, and each message is at most 2,000 characters.
  • Before sharing logs, remove tokens and other private information.

For additional help, see the FAQ or open an issue.

Clone this wiki locally