BetterDiscord CLI

Overview | Compatibility | Installation | Quick Start | Usage | FAQ | Development

A cross-platform command-line interface for installing, updating, and managing BetterDiscord.

Overview

This repository contains the source code for the BetterDiscord CLI. It is a native Go command-line tool for installing, removing, and maintaining BetterDiscord across supported Discord desktop installations.

Features

• Easy installation and uninstallation of BetterDiscord
• Support for multiple Discord channels (Stable, PTB, Canary)
• Automatically stops and restarts Discord during install/uninstall
• Optional BetterDiscord development builds via --dev
• Discover Discord installs and suggested paths
• Manage plugins and themes (list, install, update, remove)
• Browse and search the BetterDiscord store
• Cross-platform support (Windows, macOS, Linux)
• Available via brew, npm, and winget for easy distribution
• Fast and lightweight Go binary

Compatibility Matrix

Platform	Minimum Version	Support Status	Notes
Windows	Windows 10+	✅	x64, ARM64, and x86 builds are available.
macOS	macOS 11+ (Big Sur)	✅	x64 and ARM64 builds are available.
Linux	Ubuntu 20.04+ and Debian 11+, openSUSE 16.2+, Fedora Linux 32+	✅	See Linux install support notes below.

Linux install support:

• Native Discord install: ✅ Supported
• Flatpak Discord install: ✅ Supported
• Snap Discord install: ❌ Unsupported due to upstream Snap packaging/runtime changes

Installation

Via Homebrew/Linuxbrew (Recommended)

brew install betterdiscord/tap/bdcli

Via npm

npm install -g @betterdiscord/cli

Via Go

go install github.com/betterdiscord/cli@latest

Via winget (Windows)

winget install betterdiscord.cli

Download Binary

Download the latest release for your platform from the releases page.

Quick Start

# Install BetterDiscord to Discord Stable
bdcli install --channel stable

# Check installation details
bdcli info

# Update BetterDiscord
bdcli update

# Uninstall from a specific channel
bdcli uninstall --channel stable

Usage

Use bdcli [command] --help for command-specific flags and examples.

Command Reference

Command	Purpose	Example
install	Install BetterDiscord to Discord	bdcli install --channel stable
uninstall	Remove BetterDiscord from Discord	bdcli uninstall --channel stable
update	Update BetterDiscord to latest	bdcli update
info	Show installation state and metadata	bdcli info
discover	Discover installs, paths, and addons	bdcli discover installs
plugins	Manage BetterDiscord plugins	bdcli plugins list
themes	Manage BetterDiscord themes	bdcli themes list
store	Search and inspect store entries	bdcli store search <query>
completion	Generate shell completion scripts	bdcli completion zsh
version	Print CLI version	bdcli version

Detailed Examples

Common Workflows

# Install / update / inspect
bdcli install --channel stable
bdcli update
bdcli info

# Uninstall from one channel
bdcli uninstall --channel stable

# Discover installed targets
bdcli discover installs

# Basic addon workflow
bdcli plugins list
bdcli themes list

Advanced Workflows

# Install or uninstall by explicit path
bdcli install --path /path/to/Discord
bdcli uninstall --path /path/to/Discord

# Global removal modes
bdcli uninstall --all
bdcli uninstall --full

# Install the BetterDiscord development build (install-only; update tracks stable)
bdcli install --dev
BDCLI_DEV_BUILD=1 bdcli install

# Check-only updates
bdcli update --check
bdcli plugins update <name|id> --check
bdcli themes update <name|id> --check

# Store browsing
bdcli store search <query>
bdcli store plugins show <id|name>
bdcli store themes show <id|name>

# Shell + automation
bdcli completion zsh
bdcli --silent install --channel stable
BDCLI_SILENT=1 bdcli update

CLI Help Output

Show Full Root Help Output

A cross-platform CLI for installing, updating, and managing BetterDiscord.

Usage:
  bdcli [flags]
  bdcli [command]

Available Commands:
  completion  Generate shell completions
  discover    Discover Discord installations and related data
  help        Help about any command
  info        Displays information about BetterDiscord installation
  install     Installs BetterDiscord to your Discord
  plugins     Manage BetterDiscord plugins
  store       Browse and search the BetterDiscord store
  themes      Manage BetterDiscord themes
  uninstall   Uninstalls BetterDiscord from your Discord
  update      Update BetterDiscord to the latest version
  version     Print the version number

Flags:
  -h, --help     help for bdcli
      --silent   Suppress non-error output

Use "bdcli [command] --help" for more information about a command.

FAQ

Does the CLI support Flatpak Discord on Linux?

Yes. Flatpak Discord installs are supported.

Why is Snap Discord unsupported on Linux?

Upstream Snap packaging changes mount Discord in a read-only filesystem, so the CLI cannot write the BetterDiscord injection into it. Native and Flatpak installs remain supported, and the CLI detects Snap installs and rejects them with a clear error instead of leaving a half-modified install.

Do I need to close Discord before installing or uninstalling?

No. The CLI stops Discord automatically before modifying it and restarts it afterward if it was running. The exception is bdcli update, which only replaces the BetterDiscord asar, you need to restart Discord manually for the update to take effect.

How do I install the BetterDiscord development build?

Use the --dev flag (or set BDCLI_DEV_BUILD=1):

bdcli install --dev

The development build is BetterDiscord's rolling canary pre-release on GitHub (unrelated to the Discord Canary channel). It is not versioned, so bdcli update always tracks the stable release. Rerun bdcli install --dev to get the newest development build.

How can I use the global BetterDiscord folder with Flatpak?

1. Grant the Flatpak app access to the BetterDiscord config directory:

flatpak --user override com.discordapp.Discord --filesystem=xdg-config/BetterDiscord:rw

2. Symlink the BetterDiscord folder into the Flatpak app config:

ln -s "${XDG_CONFIG_HOME:-$HOME/.config}/BetterDiscord" "$HOME/.var/app/com.discordapp.Discord/config/BetterDiscord"

Replace com.discordapp.Discord with your Discord Flatpak app ID if it differs on your system.

Development

Prerequisites

• Go 1.26 or higher
• Task (optional)
• GoReleaser (optional, release builds)

Quick Dev Loop

# Install dependencies
task setup

# Run locally
task run -- install stable

# Test + build
task test
task build

Setup

Clone the repository and install dependencies:

git clone https://github.com/BetterDiscord/cli.git
cd cli
task setup  # Or: go mod download

Additional Tasks And Release Flow

# Task catalog
task --list-all

# Useful checks
task coverage
task coverage:html
task check

# Multi-platform builds
task build:all

# Release helpers
task release:snapshot
task release

Release outline:

1. Create and push a new tag.
2. GitHub Actions starts to build and draft all releases.
   1. Build binaries for Windows, macOS, and Linux.
   2. Publish to package managers (Homebrew, npm, winget, etc.).
   3. Generate release notes on GitHub.
3. Verify releases.
   1. Verify pull request to winget is valid
   2. Verify successful commit to homebrew tap
   3. Verify successful publish to npm
4. Manually cleanup and finish any steps missed by automation

Project Structure

Show Project Structure

.
├── cmd/                  # Cobra commands
│   ├── install.go       # Install command
│   ├── update.go        # Update command
│   ├── info.go          # Info command
│   ├── discover.go      # Discover command
│   ├── plugins.go       # Plugins commands
│   ├── themes.go        # Themes commands
│   ├── store.go         # Store commands
│   ├── uninstall.go     # Uninstall command
│   ├── version.go       # Version command
│   └── root.go          # Root command
├── internal/            # Internal packages
│   ├── betterdiscord/  # BetterDiscord installation logic
│   ├── discord/        # Discord path resolution and injection
│   ├── models/         # Data models
│   ├── output/         # Output formatting
│   ├── utils/          # Utility functions
│   └── wsl/            # WSL detection and path mapping
├── main.go             # Entry point
├── Taskfile.yml        # Task automation
└── .goreleaser.yaml    # Release configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For information on contributing to this project, please see CONTRIBUTING.md.

---

Made with ❤️ by the BetterDiscord Team