✦ Nucleus ✦

 

---

✦ Overview ✦

A blazingly fast CLI for managing and supercharging nucleus-shell.

---

Features

• Start and stop Nucleus Shell
• Reload running QuickShell instances
• Foreground (debug) and daemonized modes
• Plugin management namespace
• Install and Update nucleus-shell
• Manage quickshell ipc's

---

Important

• You can also join the discord server for help.
• Before reporting an issue: If you encounter a problem in the current release, please first test against the latest source code by cloning the repository (git clone ...). This ensures you are not reporting an issue that has already been fixed. Only open an issue if the problem is still reproducible on the latest source.

---

Requirements

• Linux
• Hyprland
• QuickShell (available in $PATH)
• Go ≥ 1.25

---

Installation

Build from source

git clone https://github.com/unf6/nucleus.git nucleus-cli
cd nucleus-cli
go mod tidy
go build

(Required)

sudo mv nucleus /usr/local/bin/

Installing Via Aur

yay -S nucleus-cli

---

Usage

nucleus <command> [flags]

---

Commands

nucleus run

Start the Nucleus Shell using QuickShell.

nucleus run

Flags

Usage:
  nucleus [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  install     Install or Update Nucleus Shell
  ipc         Interact with the shell via IPC
  plugins     Manage Nucleus Shell plugins
  run         Start The Nucleus Shell

Flags:
  -h, --help   help for nucleus

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

Examples

Run normally (daemonized):

nucleus run

Run in foreground:

nucleus run --debug

Restart shell cleanly:

nucleus run --reload

---

nucleus plugins

Plugin management command namespace.

nucleus plugins

Plugin sources:

• Official: https://github.com/xZepyx/nucleus-plugins.git

---

Configuration Paths

The CLI expects Nucleus Shell to be installed at:

~/.config/quickshell/nucleus-shell/

Required file:

shell.qml

The shell is considered installed if this file exists:

~/.config/quickshell/nucleus-shell/shell.qml

If missing, nucleus run will refuse to start.

---

Related Repositories

• nucleus-shell: https://github.com/xZepyx/nucleus-shell
• nucleus-plugins: https://github.com/xZepyx/nucleus-plugins
• nucleus-colorschemes: https://github.com/xZepyx/nucleus-colorschemes
• nucleus(cli): https://github.com/unf6/nucleus (this repo)
• zenith(ai backend): https://github.com/xZepyx/zenith

---