StuffAnThings/qbit_manage
1
1
Fork 0
mirror of https://github.com/StuffAnThings/qbit_manage.git synced 2025-09-10 15:14:36 +08:00
Code Issues Projects Releases Packages Wiki Activity

chore(docs): Sync docs to wiki [skip-cd]

Actionbot 2025-08-17 02:07:04 +00:00
parent 90899f05db
commit 6c18410711
7 changed files with 330 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Commands.md

@ -8,7 +8,7 @@
| `-r` or`--run` | QBT_RUN | N/A | Run without the scheduler. Script will exit after completion. | False |
| `-sch` or `--schedule` | QBT_SCHEDULE | N/A | Schedule to run every x minutes or choose customize schedule via [cron](https://crontab.guru/examples.html). (Default set to 1440 (1 day)) | 1440 |
| `-sd` or `--startup-delay` | QBT_STARTUP_DELAY | N/A | Set delay in seconds on the first run of a schedule (Default set to 0) | 0 |
| `-c CONFIG` or `--config-file CONFIG` | QBT_CONFIG | N/A | This is used if you want to use a different name for your config.yml. `Example: tv.yml`. Supports wildcards to use multiple configs. `Example: config-*.yml` | config.yml |
| `-c CONFIG` or `--config-file CONFIG` | QBT_CONFIG | N/A | Override the default config file location. By default, qbit_manage looks for `config.yml` in platform-specific directories (see [Config-Setup](Config-Setup.md) for details). Use this to specify a custom path or filename. `Example: tv.yml`. Supports wildcards to use multiple configs. `Example: config-*.yml` | Platform-specific |
| `-lf LOGFILE,` or `--log-file LOGFILE,` | QBT_LOGFILE | N/A | This is used if you want to use a different name for your log file. `Example: tv.log` | activity.log |
| `-re` or `--recheck` | QBT_RECHECK | recheck | Recheck paused torrents sorted by lowest size. Resume if Completed. | False |
| `-cu` or `--cat-update` | QBT_CAT_UPDATE | cat_update | Use this if you would like to update your categories or move from one category to another. | False |

44
Config-Setup.md

@ -3,7 +3,19 @@
The script utilizes a YAML config file to load information to connect to the various APIs you can connect with. Alternatively, you can configure qBit Manage using the [Web UI](Web-UI.md), which requires the [Web API](Web-API.md) to be enabled.
By default, the script looks at `/config/config.yml` when running locally or `/app/config.yml` in docker for the Configuration File unless otherwise specified.
## Default Configuration File Locations
The script looks for the configuration file in different locations depending on your platform:
### Local Installation (Platform-specific)
- **Windows**: `%APPDATA%\qbit-manage\config.yml` (typically `C:\Users\<username>\AppData\Roaming\qbit-manage\config.yml`)
- **macOS**: `~/Library/Application Support/qbit-manage/config.yml`
- **Linux/Unix**: `~/.config/qbit-manage/config.yml` (or `$XDG_CONFIG_HOME/qbit-manage/config.yml` if XDG_CONFIG_HOME is set)
### Docker Installation
- `/app/config.yml` (inside the container)
You can override the default location by using the `--config-file` or `-c` command line option to specify a custom path.
A template Configuration File can be found in the repo [config/config.yml.sample](https://github.com/StuffAnThings/qbit_manage/blob/master/config/config.yml.sample).
@ -265,7 +277,7 @@ Provide webhook notifications based on event triggers
Payload will be sent on any errors
```json
```yaml
{
"function": "run_error", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -279,7 +291,7 @@ Payload will be sent on any errors
Payload will be sent at the start of the run
```json
```yaml
{
"function": "run_start", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -294,7 +306,7 @@ Payload will be sent at the start of the run
Payload will be sent at the end of the run
```json
```yaml
{
"function": "run_end", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -327,7 +339,7 @@ Payload will be sent at the end of the run
Payload will be sent when rechecking/resuming a torrent that is paused
```json
```yaml
{
"function": "recheck", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -344,7 +356,7 @@ Payload will be sent when rechecking/resuming a torrent that is paused
Payload will be sent when updating torrents with missing category
```json
```yaml
{
"function": "cat_update", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -361,7 +373,7 @@ Payload will be sent when updating torrents with missing category
Payload will be sent when updating torrents with missing tag
```json
```yaml
{
"function": "tag_update", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -378,7 +390,7 @@ Payload will be sent when updating torrents with missing tag
Payload will be sent when Unregistered Torrents are found
```json
```yaml
{
"function": "rem_unregistered", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -397,7 +409,7 @@ Payload will be sent when Unregistered Torrents are found
Payload will be sent when trackers with errors are tagged/untagged
```json
```yaml
{
"function": "tag_tracker_error", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -411,7 +423,7 @@ Payload will be sent when trackers with errors are tagged/untagged
}
```
```json
```yaml
{
"function": "untag_tracker_error", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -428,7 +440,7 @@ Payload will be sent when trackers with errors are tagged/untagged
Payload will be sent when Orphaned Files are found and moved into the orphaned folder
```json
```yaml
{
"function": "rem_orphaned", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -443,7 +455,7 @@ Payload will be sent when Orphaned Files are found and moved into the orphaned f
Payload will be sent when no hard links are found for any files in a particular torrent
```json
```yaml
{
"function": "tag_nohardlinks", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -458,7 +470,7 @@ Payload will be sent when no hard links are found for any files in a particular
Payload will be sent when hard links are found for any torrents that were previously tagged with `noHL`
```json
```yaml
{
"function": "untag_nohardlinks", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -475,7 +487,7 @@ Payload will be sent when hard links are found for any torrents that were previo
Payload will be sent when Share Limits are updated for a specific group
```json
```yaml
{
"function": "share_limits", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -492,7 +504,7 @@ Payload will be sent when Share Limits are updated for a specific group
Payload will be sent when `cleanup` flag is set to true and torrent meets share limit criteria.
```json
```yaml
{
"function": "cleanup_share_limits", // Webhook Trigger keyword
"title": str, // Title of the Payload
@ -511,7 +523,7 @@ Payload will be sent when `cleanup` flag is set to true and torrent meets share
Payload will be sent when files are deleted/cleaned up from the various folders
```json
```yaml
{
"function": "cleanup_dirs", // Webhook Trigger keyword
"location": str, // Location of the folder that is being cleaned

18
Home.md

@ -4,9 +4,21 @@ This wiki should tell you everything you need to know about the script to get it
## Getting Started
1. Install qbit_manage either by installing Python3.9.0+ on the localhost and following the [Local Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Local-Installations) Guide or by installing Docker and following the [Docker Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Docker-Installation) Guide or the [unRAID Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Unraid-Installation) Guide.<br>
1. Once installed, you have to [set up your Configuration](https://github.com/StuffAnThings/qbit_manage/wiki/Config-Setup) by create a [Configuration File](https://github.com/StuffAnThings/qbit_manage/blob/master/config/config.yml.sample) filled with all your values to connect to your qBittorrent instance.
1. Please refer to the list of [Commands](https://github.com/StuffAnThings/qbit_manage/wiki/Commands) that can be used with this tool.
1. **Choose your installation method:**
- **Desktop App** (Recommended): Download and install the GUI application for [Windows, macOS, or Linux](Installation.md#desktop-app-installation)
- **Standalone Binary**: Download the command-line executable for [Windows, macOS, or Linux](Installation.md#standalone-binary-installation)
- **Docker**: Follow the [Docker Installation](Docker-Installation) guide for containerized environments
- **Python/Source**: Install from [PyPI or source code](Local-Installations) for development
- **unRAID**: Follow the [unRAID Installation](Unraid-Installation) guide for unRAID systems
2. **Configure qbit_manage:**
- Desktop app users: Configuration is handled through the GUI
- Command-line users: [Set up your Configuration](Config-Setup) by creating a [Configuration File](https://github.com/StuffAnThings/qbit_manage/blob/master/config/config.yml.sample) with your qBittorrent connection details
3. **Start using qbit_manage:**
- Review the [Commands](Commands) documentation to understand available features
- Try the [Web UI](Web-UI) for an intuitive configuration experience
- Use the [Web API](Web-API) for automation and integration
## Support

125
Installation.md

@ -1,7 +1,120 @@
# Installation Table of Contents
# Installation Options
- [Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Installation)
- [unRAID Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Unraid-Installation)
- [Local Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Local-Installations)
- [NIX Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Nix-Installation)
- [Docker Installation](https://github.com/StuffAnThings/qbit_manage/wiki/Docker-Installation)
qbit_manage offers multiple installation methods to suit different use cases:
## Installation Methods
### 1. Desktop App (Recommended for most users)
- **Windows**: Download and run the `.exe` installer
- **macOS**: Download and install the `.dmg` package
- **Linux**: Download and install the `.deb` package
The desktop app provides a graphical interface and automatically handles configuration file setup.
### 2. Standalone Binary (Command-line)
- **Windows**: `qbit-manage-windows-amd64.exe`
- **macOS**: `qbit-manage-macos-arm64` (Apple Silicon) or `qbit-manage-macos-x86_64` (Intel)
- **Linux**: `qbit-manage-linux-amd64`
Perfect for server environments, automation, or users who prefer command-line tools.
### 3. Docker Container
- Multi-architecture support (amd64, arm64, arm/v7)
- Ideal for containerized environments and NAS systems
### 4. Python Installation
- Install from source or PyPI
- For developers or users who want to modify the code
## Detailed Installation Guides
- [Desktop App Installation](#desktop-app-installation)
- [Standalone Binary Installation](#standalone-binary-installation)
- [Docker Installation](Docker-Installation)
- [Python/Source Installation](Local-Installations)
- [unRAID Installation](Unraid-Installation)
- [NIX Installation](Nix-Installation)
## Desktop App Installation
### Windows
1. Download `qbit-manage-*-desktop-installer-setup.exe` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
2. Run the installer and follow the setup wizard
3. Launch qbit_manage from the Start Menu or desktop shortcut
4. The app will automatically create the configuration directory and files
### macOS
1. Download `qbit-manage-*-desktop-installer.dmg` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
2. Open the DMG file and drag qbit_manage to your Applications folder
3. Launch qbit_manage from Applications (you may need to allow it in System Preferences > Security & Privacy)
4. The app will automatically create the configuration directory and files
### Linux
1. Download `qbit-manage-*-desktop-installer.deb` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
2. Install using your package manager:
```bash
sudo dpkg -i qbit-manage-*-desktop-installer.deb
sudo apt-get install -f # Fix any dependency issues
```
3. Launch qbit_manage from your applications menu or run `qbit-manage` in terminal
4. The app will automatically create the configuration directory and files
## Standalone Binary Installation
### Windows
1. Download `qbit-manage-windows-amd64.exe` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
2. Place the executable in a directory of your choice (e.g., `C:\Program Files\qbit-manage\`)
3. Add the directory to your PATH environment variable (optional)
4. Run from Command Prompt or PowerShell:
```cmd
qbit-manage-windows-amd64.exe --help
```
### macOS
1. Download the appropriate binary from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases):
- `qbit-manage-macos-arm64` for Apple Silicon Macs (M1, M2, M3, etc.)
- `qbit-manage-macos-x86_64` for Intel Macs
2. Make the binary executable:
```bash
chmod +x qbit-manage-macos-*
```
3. Move to a directory in your PATH (optional):
```bash
sudo mv qbit-manage-macos-* /usr/local/bin/qbit-manage
```
4. Run the binary:
```bash
./qbit-manage-macos-* --help
```
### Linux
1. Download `qbit-manage-linux-amd64` from the [releases page](https://github.com/StuffAnThings/qbit_manage/releases)
2. Make the binary executable:
```bash
chmod +x qbit-manage-linux-amd64
```
3. Move to a directory in your PATH (optional):
```bash
sudo mv qbit-manage-linux-amd64 /usr/local/bin/qbit-manage
```
4. Run the binary:
```bash
./qbit-manage-linux-amd64 --help
```
## Quick Reference: Default Configuration File Locations
### Desktop App & Standalone Binary
- **Windows**: `%APPDATA%\qbit-manage\config.yml`
- **macOS**: `~/Library/Application Support/qbit-manage/config.yml`
- **Linux**: `~/.config/qbit-manage/config.yml`
### Docker Installation
- **Container Path**: `/app/config.yml`
- **Host Mount**: Typically mounted from `/path/to/your/config:/config`
### Custom Location
You can override the default location using the `--config-file` or `-c` command line option:
```bash
qbit-manage --config-file /path/to/your/config.yml
```

173
Local-Installations.md

@ -1,64 +1,179 @@
# Local Installations
# Python/Source Installation
Below is a simple high level set of instructions for cloning the repository and executing qbit_manage
This guide covers installing qbit_manage from source code or PyPI for development purposes or when you need the latest features.
* Requires `python 3.9.0`. Dependencies must be installed by running:
**Note**: For most users, we recommend using the [Desktop App or Standalone Binary](Installation.md) instead, as they're easier to install and use.
Navigate to the directory you'd liked to clone the repo into
## Prerequisites
Clone the repo
* Python 3.9.0 or higher
* pip (Python package installer)
* Git (for source installation)
## Installation Methods
### Method 1: Install from PyPI (Recommended)
```bash
git clone https://github.com/StuffAnThings/qbit_manage
pip install qbit-manage
```
Install requirements
### Method 2: Install from Source
Navigate to the directory where you'd like to clone the repository:
```bash
# Clone the repository
git clone https://github.com/StuffAnThings/qbit_manage
cd qbit_manage
# Install the package
pip install .
```
If there are issues installing dependencies try:
If you encounter dependency issues, try:
```bash
pip install . --ignore-installed
```
## Usage
### Method 3: Development Installation
To run the script in an interactive terminal run:
* copy the `config.yml.sample` file to `config.yml`
* Fill out the config file as outlined in the [Config-Setup](https://github.com/StuffAnThings/qbit_manage/wiki/Config-Setup)
Run the script `-h` to see a list of commands
For development or to get the latest unreleased features:
```bash
# Clone the repository
git clone https://github.com/StuffAnThings/qbit_manage
cd qbit_manage
# Install in development mode
pip install -e .
```
## Configuration File Setup
After installation, qbit_manage will look for configuration files in platform-specific locations:
- **Windows**: `%APPDATA%\qbit-manage\config.yml`
- **macOS**: `~/Library/Application Support/qbit-manage/config.yml`
- **Linux/Unix**: `~/.config/qbit-manage/config.yml`
### Setting up the Configuration
1. Create the configuration directory:
```bash
# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\qbit-manage"
# macOS/Linux
mkdir -p ~/.config/qbit-manage # Linux
mkdir -p ~/Library/Application\ Support/qbit-manage # macOS
```
2. Copy the sample configuration:
```bash
# From the cloned repository
cp config/config.yml.sample ~/.config/qbit-manage/config.yml # Linux
cp config/config.yml.sample ~/Library/Application\ Support/qbit-manage/config.yml # macOS
copy config\config.yml.sample "%APPDATA%\qbit-manage\config.yml" # Windows
```
3. Edit the configuration file as outlined in the [Config-Setup](Config-Setup.md) guide.
**Alternative**: You can place the config file anywhere and specify its location using the `--config-file` option.
## Usage
### Running the Script
### Basic Usage
Run the script with `-h` to see all available commands:
```bash
qbit-manage -h
# or if installed from source
python qbit_manage.py -h
```
### Web API and Web UI
To run the Web API and Web UI, use the `--web-server` flag:
### Common Usage Examples
**Run with default configuration:**
```bash
python qbit_manage.py --web-server
qbit-manage
```
You can then access the Web UI in your browser, typically at `http://localhost:8080`.
### Config
To choose the location of the YAML config file
**Run specific commands:**
```bash
python qbit_manage.py --config-file <path_to_config>
qbit-manage --cat-update --tag-update
```
### Log
**Run with Web API and Web UI:**
```bash
qbit-manage --web-server
```
You can then access the Web UI in your browser at `http://localhost:8080`.
To choose the location of the Log File
**Use custom configuration file:**
```bash
qbit-manage --config-file /path/to/your/config.yml
```
**Run in dry-run mode (preview changes without applying them):**
```bash
qbit-manage --dry-run --cat-update --tag-update
```
**Run on a schedule:**
```bash
qbit-manage --schedule 1440 # Run every 24 hours (1440 minutes)
```
### Command Line Options
| Option | Description |
|--------|-------------|
| `--config-file`, `-c` | Specify custom config file location |
| `--log-file`, `-lf` | Specify custom log file location |
| `--web-server`, `-ws` | Start the web server for API and UI |
| `--port`, `-p` | Web server port (default: 8080) |
| `--dry-run`, `-dr` | Preview changes without applying them |
| `--schedule`, `-sch` | Run on a schedule (minutes) |
| `--run`, `-r` | Run once and exit (no scheduler) |
For a complete list of commands and options, see the [Commands](Commands.md) documentation.
### Virtual Environment (Recommended)
For Python installations, it's recommended to use a virtual environment:
```bash
python qbit_manage.py --log-file <path_to_log>
# Create virtual environment
python -m venv qbit-manage-env
# Activate virtual environment
# Linux/macOS:
source qbit-manage-env/bin/activate
# Windows:
qbit-manage-env\Scripts\activate
# Install qbit-manage
pip install qbit-manage
# Run qbit-manage
qbit-manage --help
```
### Updating
**PyPI installation:**
```bash
pip install --upgrade qbit-manage
```
**Source installation:**
```bash
cd qbit_manage
git pull
pip install . --upgrade
```

21
Nix-Installation.md

@ -20,6 +20,23 @@ pip install .
* Create Config
**Note:** If using the standalone desktop app, it will automatically create the necessary directories and config files. For command-line usage, you have these options:
**Option 1 - Use default system location:**
```bash
# Create the config directory
mkdir -p ~/.config/qbit-manage
# Copy the sample config
cp config/config.yml.sample ~/.config/qbit-manage/config.yml
# Edit the config file
nano ~/.config/qbit-manage/config.yml
```
**Option 2 - Keep in project directory:**
```bash
cd config
cp config.yml.sample config.yml
@ -120,12 +137,12 @@ chmod +x qbm-update.sh
To run qBit Manage with the Web API and Web UI enabled, execute the `qbit_manage.py` script with the `--web-server` flag:
**If using the default config location (`~/.config/qbit-manage/config.yml`):**
```bash
python qbit_manage.py --web-server
```
You can also specify a configuration file and log file:
**If using a custom config location:**
```bash
python qbit_manage.py --web-server --config-file /path/to/your/config.yml --log-file /path/to/your/activity.log
```

7
_Sidebar.md

@ -1,9 +1,10 @@
- [Home](Home)
- [Installation](Installation)
- [unRAID Installation](Unraid-Installation)
- [Local Installation](Local-Installations)
- [NIX Installation](Nix-Installation)
- [Desktop App & Binary Installation](Installation)
- [Docker Installation](Docker-Installation)
- [Python/Source Installation](Local-Installations)
- [unRAID Installation](Unraid-Installation)
- [NIX Installation](Nix-Installation)
- [V4 Migration Guide](v4-Migration-Guide)
- [Config Setup](Config-Setup)
- [Sample Config File](Config-Setup#config-file)