Skip to content

Commit 1b8cb94

Browse files
muzaffarmhdmuzaffarmhd
committed
Update readme.md
1 parent 2de68dd commit 1b8cb94

File tree

1 file changed

+77
-114
lines changed

1 file changed

+77
-114
lines changed

‎README.md‎

Lines changed: 77 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,14 @@
11
# Zuffer CLI
22

3-
**A powerful CLI utility to automate and simplify Discord server management tasks.**
3+
**A CLI utility to automate and simplify Discord server management tasks.**
44

55
---
66

7-
87
Zuffer is currently under active development. While many core features are functional, it's not yet complete. Expect rough edges, potential bugs, and changes as development progresses.
98

109
**Upcoming Features:**
11-
* Integration of Discord Slash Commands for easier in-server use.
12-
* automated tests.
10+
* More robust error handling and user feedback.
11+
* Expansion of automated tests.
1312

1413
---
1514

@@ -30,217 +29,181 @@ Before installing Zuffer CLI, please ensure you have the following system depend
3029
* **Windows & macOS:** Usually included with Python.
3130
* **Linux:** You might need to install it separately. For example, on Debian/Ubuntu: `sudo apt update && sudo apt install python3-tk`. On Fedora: `sudo dnf install python3-tkinter`.
3231

33-
3432
## Table of Contents
3533

3634
* [About](#about)
3735
* [Features](#features)
3836
* [Installation](#installation)
3937
* [Getting Started](#getting-started)
4038
* [Command Reference](#command-reference)
41-
* [Authentication](#authentication)
39+
* [Core](#core)
4240
* [Channel Management](#channel-management)
4341
* [Embed Messages](#embed-messages)
4442
* [Welcomer Bot](#welcomer-bot)
45-
* [Guild Information](#guild-information)
43+
* [Role Management](#role-management)
44+
* [Music Bot](#music-bot)
4645
* [Contributing](#contributing)
4746
* [License](#license)
4847

4948
---
5049

5150
## About
5251

53-
Zuffer is designed to help Discord server administrators and moderators streamline common tasks through a command-line interface and interactive GUIs. From bulk channel creation to sophisticated welcome messages, Zuffer aims to be your go-to tool for efficient server management.
52+
Zuffer helps Discord server administrators and moderators streamline common tasks through a command-line interface and interactive GUIs.
5453

5554
---
5655

5756
## Features
5857

59-
* **Secure Credential Management:** Store your Discord Bot Token and Client ID securely using your system's native keyring.
58+
* **Secure Credential Management:** Stores Discord Bot Token and Client ID using your system's native keyring.
6059
* **Bulk Channel Creation:**
61-
* Create multiple public text or voice channels with sequential naming (e.g., `team-1`, `team-2`).
62-
* Create private channels automatically linked to new roles, with options to grant access to existing roles (e.g., "Moderators").
63-
* **Interactive Embed Builder GUI:** A user-friendly graphical interface to visually construct and send rich embed messages to your Discord channels. Supports exporting and importing embed designs as JSON.
60+
* Create multiple public text or voice channels with sequential naming.
61+
* Create private channels automatically linked to new roles, with options to grant access to existing roles.
62+
* **Interactive Embed Builder GUI:** Visually construct and send rich embed messages. Supports exporting/importing designs as JSON.
6463
* **Customizable Welcomer Bot & GUI:**
65-
* Design unique welcome images with an intuitive GUI configurator:
66-
* Set custom image dimensions.
67-
* Choose solid color backgrounds or use your own images.
68-
* Configure avatar visibility, size, and position (draggable on a preview canvas).
69-
* Add multiple, draggable text elements with placeholders (like `{username}`), custom fonts, sizes, and colors.
70-
* Run a dedicated bot instance that automatically sends these personalized welcome images when new members join.
71-
* Test your welcome image setup by simulating a member join event.
72-
* Save and load welcome image configurations as JSON files.
73-
* **Guild Information:** List all Discord guilds (servers) your bot is a member of.
74-
* **Cached Data:** Caches guild information locally for faster operations and selections in commands.
64+
* Design unique welcome images with an intuitive GUI: custom dimensions, backgrounds (color/image), draggable avatar, and multiple draggable text elements with placeholders and font customization.
65+
* Run a bot to automatically send personalized welcome images.
66+
* Test setup by simulating a member join.
67+
* Save/load configurations as JSON.
68+
* **Role Management Bot:**
69+
* Allows users to claim/unclaim roles via slash commands (`/claim`, `/unclaim`).
70+
* Option to enforce unique roles per user (one non-`@everyone` role at a time).
71+
* **Basic Music Bot:**
72+
* Play `.mp3` files from a local directory on loop in a voice channel.
73+
* **Guild Information:** List Discord guilds your bot is a member of.
74+
* **Cached Data:** Caches guild information locally for faster operations.
7575

7676
---
7777

7878
## Installation
7979

80-
1. **Prerequisites:**
81-
* Python 3.8 or higher.
82-
* `pip` (Python package installer).
83-
* A Discord Bot Token and Client ID. You can obtain these by creating a new application and bot on the [Discord Developer Portal](https://discord.com/developers/applications).
80+
1. **Prerequisites:** Ensure all system dependencies listed [above](#prerequisites) are met. You'll also need a Discord Bot Token and Client ID from the [Discord Developer Portal](https://discord.com/developers/applications).
8481

8582
2. **Clone the repository:**
8683
```bash
87-
git clone https://github.com/muzaffarmhd/zuffer-cli.git
84+
git clone https://github.com/muzaffarmhd/zuffer-cli.git
8885
cd zuffer-cli
8986
```
9087

9188
3. **Set up a Virtual Environment (Recommended):**
9289
```bash
9390
python -m venv venv
9491
```
95-
Activate the virtual environment:
96-
* On macOS and Linux: `source venv/bin/activate`
97-
* On Windows: `venv\Scripts\activate`
92+
Activate it:
93+
* macOS/Linux: `source venv/bin/activate`
94+
* Windows: `venv\Scripts\activate`
9895

9996
4. **Install the CLI:**
100-
With the virtual environment activated, install Zuffer and its dependencies:
10197
```bash
10298
pip install .
10399
```
104-
This command reads the `pyproject.toml` file and installs the `zuffer` CLI tool.
105100

106101
---
107102

108103
## Getting Started
109104

110105
1. **Login:**
111-
The first and most crucial step is to configure Zuffer with your Discord bot's credentials. Run:
106+
Configure Zuffer with your Discord bot's credentials:
112107
```bash
113108
zuffer login
114109
```
115-
You will be prompted to enter your Bot Token and Client ID. These are stored securely in your system's keyring.
110+
You'll be prompted for your Bot Token and Client ID.
116111

117112
2. **Refresh Guild Cache:**
118-
After logging in, or whenever your bot joins or leaves servers, refresh the local cache of guilds:
113+
After login, or if your bot's server membership changes, refresh the local guild cache:
119114
```bash
120115
zuffer refresh
121116
```
122-
This ensures that commands requiring guild selection have the most up-to-date list.
123117
124118
3. **Explore Commands:**
125-
To see all available commands and their general options, use:
119+
See all commands:
126120
```bash
127121
zuffer --help
128122
```
129-
For help with a specific command or subcommand, use:
123+
Help for a specific command:
130124
```bash
131125
zuffer <command> --help
132-
zuffer <group> <subcommand> --help
126+
# Example
127+
zuffer welcome run --help
133128
```
134-
Example: `zuffer welcome run --help`
135129
136130
---
137131
138132
## Command Reference
139133
140-
### Authentication
141-
142-
These commands manage your bot's credentials.
134+
### Core
143135
144136
* **`zuffer login`**
145-
* Description: Securely stores your Discord Bot Token and Client ID. This is the first command you should run.
146-
* Usage: `zuffer login` (Prompts for Token and Client ID)
147-
137+
* Description: Securely stores your Discord Bot Token and Client ID.
148138
* **`zuffer reset`**
149-
* Description: Removes your stored Discord Bot Token and Client ID from the system's keyring.
150-
* Usage: `zuffer reset` (Asks for confirmation)
151-
* Note: After resetting, you might need to generate a new token from the Discord Developer Portal if you intend to use the same bot.
152-
139+
* Description: Removes stored Discord Bot Token and Client ID.
153140
* **`zuffer refresh`**
154-
* Description: Fetches and updates the local cache of guilds (servers) your bot is currently in. Run this after `login` or if your bot's guild membership changes.
155-
* Usage: `zuffer refresh`
141+
* Description: Updates the local cache of guilds your bot is in.
142+
* **`zuffer list`**
143+
* Description: Lists guilds the authenticated bot is a member of. (Requires `zuffer refresh` first).
156144
157145
### Channel Management
158146
159-
Create and manage channels in bulk.
160-
161147
* **`zuffer create-channels`**
162-
* Description: Creates multiple public text or voice channels in a selected guild based on a naming pattern.
163-
* Options:
164-
* `-t, --type [voice|text]`: (Required) The type of channels to create.
165-
* `--name TEXT`: (Required) The base name for the channels (e.g., "session" will create "session-1", "session-2", etc.).
166-
* `--start INTEGER`: (Required) The starting number for the channel sequence.
167-
* `--end INTEGER`: (Required) The ending number for the channel sequence.
148+
* Description: Creates multiple public text or voice channels.
149+
* Options: `-t, --type [voice|text]`, `--name TEXT`, `--start INTEGER`, `--end INTEGER`.
168150
* Usage: `zuffer create-channels -t voice --name game-room --start 1 --end 5`
169-
* You will be prompted to select a guild from the cached list.
170151
171152
* **`zuffer create-private`**
172-
* Description: Creates multiple private text or voice channels. For each channel created (e.g., `team-alpha-1`), a corresponding role (e.g., `team-alpha-1`) is also created and given exclusive access to that channel.
173-
* Options:
174-
* `-t, --type [voice|text]`: (Required) The type of channels to create.
175-
* `--name TEXT`: (Required) The base name for the channels and associated roles.
176-
* `--start INTEGER`: (Required) The starting number for the sequence.
177-
* `--end INTEGER`: (Required) The ending number for the sequence.
178-
* `--exclude TEXT`: (Optional) A comma-separated list of existing role names (e.g., "Moderator,Admin") that should *also* be granted access to all newly created private channels.
179-
* Usage: `zuffer create-private -t text --name project-zeta --start 1 --end 3 --exclude "Coordinator,Lead"`
180-
* You will be prompted to select a guild.
153+
* Description: Creates private text/voice channels with corresponding roles.
154+
* Options: `-t, --type [voice|text]`, `--name TEXT`, `--start INTEGER`, `--end INTEGER`, `--exclude TEXT` (comma-separated existing role names for access).
155+
* Usage: `zuffer create-private -t text --name project-zeta --start 1 --end 3 --exclude "Coordinator"`
181156
182157
### Embed Messages
183158
184159
* **`zuffer embed`**
185-
* Description: Opens an interactive GUI to build a Discord embed message. Once the embed is designed, you'll be prompted to enter a Channel ID to send it to.
186-
* Usage: `zuffer embed`
187-
* **GUI Features:**
188-
* Set main message content (text that appears outside/above the embed).
189-
* Configure embed properties: title, URL, description, color (with a color picker).
190-
* Define author block: name, URL, icon URL.
191-
* Set main image URL and thumbnail URL for the embed.
192-
* Add a footer: text and icon URL.
193-
* Include multiple fields, each with a name, value, and an inline display option.
194-
* Optionally add a current timestamp to the embed.
195-
* **Export/Import:** Save your embed designs to a JSON file and load them later to reuse or modify.
160+
* Description: Opens a GUI to build and send a Discord embed message. Prompts for Channel ID.
161+
* **GUI Features:** Content, title, URL, description, color, author, image, thumbnail, footer, fields, timestamp. Supports JSON export/import.
196162
197163
### Welcomer Bot
198164
199-
Set up a bot to greet new server members with a custom-designed image.
200-
201165
* **`zuffer welcome config`**
202-
* Description: Opens an interactive GUI to design and configure the welcome image.
203-
* Usage: `zuffer welcome config`
204-
* **GUI Features:**
205-
* **Canvas & Preview:** See a live preview of your welcome image as you design it.
206-
* **Image Dimensions:** Set the width and height of the final welcome image.
207-
* **Background:** Choose a solid background color (with a color picker) or upload a custom background image.
208-
* If you use a custom image, it will be copied to an `assets` subdirectory relative to where you save your configuration JSON file (e.g., if config is `myconfigs/welcome_config.json`, image goes to `myconfigs/assets/your_image.png`).
209-
* **Avatar:** Control the new member's avatar display: visibility, size, and position (draggable on the canvas).
210-
* **Text Elements:** Add multiple text items. Each can have:
211-
* Custom content (supports the `{username}` placeholder, which will be replaced with the new member's name).
212-
* Draggable position on the canvas.
213-
* Selectable font family, font size, and text color (with a color picker).
214-
* **Note on Fonts:** The tool attempts to find common system fonts. For custom fonts or more reliable font rendering, place your `.ttf` font files in an `assets/fonts/` directory located in the same directory as your saved welcome configuration JSON file. For example, if your config is `conf/welcome.json`, custom fonts should be in `conf/assets/fonts/myfont.ttf`.
215-
* **Save/Load:** Save your complete welcome image design to a JSON file. Load existing configurations to edit or use them.
166+
* Description: Opens a GUI to design the welcome image.
167+
* **GUI Features:** Canvas preview, dimensions, background (color/image), avatar (visibility, size, position), multiple draggable text elements (content with `{username}`, font, size, color). Supports JSON save/load.
168+
* **Custom Backgrounds:** Copied to `assets/` relative to the saved config JSON.
169+
* **Custom Fonts:** Place `.ttf` files in `assets/fonts/` relative to the saved config JSON.
216170
217171
* **`zuffer welcome run`**
218-
* Description: Runs the Discord Welcomer Bot, which listens for new members and sends the configured welcome image.
172+
* Description: Runs the Welcomer Bot to greet new members.
219173
* Options:
220-
* `-c, --config FILEPATH`: (Required) Path to the welcome image configuration JSON file (previously created using `zuffer welcome config`). The bot will look for assets (like background images and fonts) relative to the directory of this config file.
221-
* `--simulate-join / --no-simulate-join`: (Optional, default: False) If `--simulate-join` is used, the bot will simulate a member join event for itself upon starting. This is useful for testing your welcome message configuration in a target channel without needing another user to join.
222-
* Usage: `zuffer welcome run -c /path/to/your/welcome_config.json --simulate-join`
174+
* `-c, --config FILEPATH`: (Required) Path to the welcome image configuration JSON.
175+
* `--simulate-join / --no-simulate-join`: (Optional) Simulate a member join for testing.
176+
* Usage: `zuffer welcome run -c /path/to/config.json --simulate-join`
223177
224-
### Guild Information
178+
### Role Management
225179
226-
* **`zuffer list`**
227-
* Description: Lists the names of all Discord guilds (servers) that the authenticated bot is currently a member of.
228-
* Usage: `zuffer list`
229-
* Note: Requires `zuffer refresh` to have been run at least once after login or after the bot's guild memberships change.
180+
* **`zuffer handle-roles`**
181+
* Description: Runs a bot that allows users to claim/unclaim roles using slash commands.
182+
* Options:
183+
* `--private`: If set, a user can only have one role (other than `@everyone`) managed by this system at a time.
184+
* **Slash Commands:**
185+
* `/claim <role_name>`: User claims the specified role.
186+
* `/unclaim <role_name>`: User removes the specified role.
187+
188+
### Music Bot
189+
190+
* **`zuffer play-music <playlist_directory>`**
191+
* Description: Runs a basic music bot that joins the voice channel of the user who types `!join` and plays `.mp3` files from the specified `<playlist_directory>` on loop.
192+
* **Bot Commands (in Discord chat):**
193+
* `!join`: Bot joins your current voice channel and starts playing music.
194+
* Note: Requires FFmpeg to be installed and in PATH.
230195
231196
---
232197
233198
## Contributing
234199
235-
Contributions are welcome and appreciated! If you'd like to contribute to Zuffer, please:
236-
237-
1. **Fork the repository** on GitHub.
238-
2. **Create a new branch** for your feature or bug fix (e.g., `git checkout -b feature/new-command` or `fix/issue-123`).
239-
3. **Make your changes** and commit them with clear, descriptive messages.
240-
4. **Push your branch** to your fork on GitHub.
241-
5. **Submit a pull request** to the main Zuffer repository, detailing the changes you've made.
200+
Contributions are welcome! Please:
242201
243-
Please ensure your code adheres to any existing style guidelines (e.g., by using a linter like Flake8 or Black if the project adopts one).
202+
1. Fork the repository.
203+
2. Create a new branch (`git checkout -b feature/your-feature` or `fix/your-fix`).
204+
3. Make changes and commit them.
205+
4. Push your branch.
206+
5. Submit a pull request.
244207
245208
---
246209

0 commit comments

Comments
 (0)