### Bitmagnet YAML Configuration Example

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Example of a Bitmagnet configuration file (`config.yml`). Configuration values can be set via YAML or environment variables, with environment variables taking precedence. This example shows settings for PostgreSQL, TMDB, logging, DHT crawler, and HTTP server options.

```yaml
# ~/.config/bitmagnet/config.yml  (or ./config.yml in CWD)

postgres:
  host: localhost
  name: bitmagnet
  user: postgres
  password: secret
  # dsn: "host=localhost user=postgres password=secret dbname=bitmagnet"  # alternative

tmdb:
  api_key: your_tmdb_api_key   # get a free key at themoviedb.org
  enabled: true                # set false to disable TMDB enrichment

log:
  level: info          # debug | info | warn | error
  json: false          # true for plain JSON logs
  development: false   # true for stack traces

dht_crawler:
  scaling_factor: 10         # multiplier for concurrency/buffer sizes
  save_files_threshold: 100  # max files saved per torrent
  save_pieces: false         # save torrent piece hashes (large, rarely useful)

http_server:
  options:                   # enabled HTTP components (default: all)
    - cors
    - graphql
    - import
    - prometheus
    - torznab
    - status
    - webui
  cors:
    allowed_origins:
      - https://my-frontend.example.com

```

--------------------------------

### Install and Run Bitmagnet CLI Workers

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Commands to install Bitmagnet natively and run its CLI workers. You can start all workers at once or select specific ones like HTTP server and queue server.

```sh
# Install natively
go install github.com/bitmagnet-io/bitmagnet

# Start all workers at once
bitmagnet worker run --all

# Start specific workers (e.g. HTTP + queue, without DHT crawler)
bitmagnet worker run --keys=http_server,queue_server

# Show CLI help
bitmagnet --help

# Show full merged configuration with sources
bitmagnet config show

# Show the current compiled classifier
bitmagnet classifier show

# Show the classifier JSON schema
bitmagnet classifier schema

```

--------------------------------

### Docker Compose for Bitmagnet Minimal Setup

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Use this Docker Compose file for a minimal Bitmagnet setup. It exposes the Web UI and API on port 3333 and BitTorrent ports on 3334. Ensure PostgreSQL is healthy before starting Bitmagnet.

```yaml
# docker-compose.yml
services:
  bitmagnet:
    image: ghcr.io/bitmagnet-io/bitmagnet:latest
    container_name: bitmagnet
    ports:
      - "3333:3333"      # API and WebUI
      - "3334:3334/tcp"  # BitTorrent
      - "3334:3334/udp"
    restart: unless-stopped
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PASSWORD=postgres
      # - TMDB_API_KEY=your_personal_api_key
    volumes:
      - ./config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      - --keys=dht_crawler   # remove this line to disable the DHT crawler
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    container_name: bitmagnet-postgres
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=bitmagnet
      - PGUSER=postgres
    shm_size: 1g
    healthcheck:
      test: [CMD-SHELL, pg_isready]
      start_period: 20s
      interval: 10s

```

--------------------------------

### Bitmagnet Text Search Syntax Examples

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Examples demonstrating Bitmagnet's full-text search operators, including exact phrases, AND/OR logic, negation, and wildcards.

```text
# Exact phrase (order matters)
"blade runner"

# Multiple unquoted terms (AND — any order)
blade runner 1982

# Phrase + unquoted year
"steamboat willie" 1928

# Followed-by operator (apple immediately before orange)
apple . orange

# OR operator
apple | orange

# Negation (contains orange, does NOT contain apple)
orange !apple

# Wildcard suffix (matches apple, application, appliance...)
appl*

# Parentheses for precedence
"banana split" | (apple !toffee)

# Combined: exact title OR (keyword without unwanted term)
"blade runner 2049" | (cyberpunk !anime)
```

--------------------------------

### Run Development Server

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/README.md

Starts the Angular development server for live preview and hot-reloading. Navigate to http://localhost:4200/ in your browser.

```bash
ng serve
```

--------------------------------

### Configure Bitmagnet with Environment Variables

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/configuration.md

Example of how to configure the same values as the YAML example using environment variables. Paths are upper-cased and dots are replaced with underscores.

```sh
LOG_JSON=true \
TMDB_API_KEY=my-api-key \
HTTP_SERVER_CORS_ALLOWED_ORIGINS=https://example1.com,https://example2.com \
  bitmagnet config show
```

--------------------------------

### Start All Bitmagnet Workers

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/installation.md

Command to start all available Bitmagnet worker processes simultaneously. This is the recommended way to run Bitmagnet for full functionality.

```sh
bitmagnet worker run --all

```

--------------------------------

### Configure Bitmagnet with YAML

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/configuration.md

Example of how to specify configuration values in a YAML file. Dots in the path represent nesting levels.

```yaml
log:
  json: true
tmdb:
  api_key: my-api-key
http_server:
  cors:
    allowed_origins:
      - https://example1.com
      - https://example2.com
```

--------------------------------

### Docker Compose Configuration for Bitmagnet

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/installation.md

Minimal Docker Compose setup for running Bitmagnet and its PostgreSQL database. Ensure you have Docker and Docker Compose installed.

```yaml
services:
  bitmagnet:
    image: ghcr.io/bitmagnet-io/bitmagnet:latest
    container_name: bitmagnet
    ports:
      # API and WebUI port:
      - "3333:3333"
      # BitTorrent ports:
      - "3334:3334/tcp"
      - "3334:3334/udp"
    restart: unless-stopped
    environment:
      - POSTGRES_HOST=postgres
      - POSTGRES_PASSWORD=postgres
    #      - TMDB_API_KEY=your_api_key
    volumes:
      - ./config:/root/.config/bitmagnet
    command:
      - worker
      - run
      - --keys=http_server
      - --keys=queue_server
      # disable the next line to run without DHT crawler
      - --keys=dht_crawler
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    container_name: bitmagnet-postgres
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    #    ports:
    #      - "5432:5432" Expose this port if you'd like to dig around in the database
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=bitmagnet
      - PGUSER=postgres
    shm_size: 1g
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready
      start_period: 20s
      interval: 10s

```

--------------------------------

### Start Specific Bitmagnet Workers

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/installation.md

Command to start individual Bitmagnet worker processes by specifying their keys. Use this if you only need certain functionalities to be active.

```sh
bitmagnet worker run --keys=http_server,queue_server,dht_crawler

```

--------------------------------

### Run Unit Tests

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/README.md

Executes unit tests using Karma. Ensure Karma is installed for this command to function.

```bash
ng test
```

--------------------------------

### Get Angular CLI Help

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/README.md

Displays help information for the Angular CLI. Refer to the Angular CLI Overview and Command Reference for more details.

```bash
ng help
```

--------------------------------

### GraphQL Search Torrents cURL Example

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

A cURL command to execute a simplified torrent search query via the GraphQL endpoint. This example searches for 'blade runner' with filters for movie content type and 1080p resolution, ordering by seeders.

```shell
curl -s -X POST http://localhost:3333/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { torrentContent { search(input: { queryString: \"blade runner\", limit: 5, facets: { contentType: { filter: [movie] }, videoResolution: { filter: [V1080p] } }, orderBy: [{ field: seeders, descending: true }] }) { totalCount items { title videoResolution seeders torrent { magnetUri } } } } }" \
  ' | jq .
```

--------------------------------

### Docker Compose Commands for Bitmagnet

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Commands to start, stop, and upgrade the Bitmagnet Docker stack. Ensure you pull the latest image before upgrading.

```sh
# Start the stack
docker compose up -d

# Upgrade
docker compose down bitmagnet
docker pull ghcr.io/bitmagnet-io/bitmagnet:latest
docker compose up -d bitmagnet

```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/README.md

Executes end-to-end tests. Requires an additional package for end-to-end testing capabilities to be installed first.

```bash
ng e2e
```

--------------------------------

### Boolean Logic for Conditions

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Use `or`, `and`, and `not` operators to build complex conditions for torrent classification. This example checks for music file extensions or a combination of name keywords and audio file types.

```yaml
or:
  - "torrent.files.map(f, f.extension in extensions.music ? f.size : - f.size).sum() > 0"
  - and:
      - "torrent.baseName.matches(keywords.music)"
      - "torrent.files.map(f, f.fileType == fileType.audio ? f.size : - f.size).sum() > 0"
```

--------------------------------

### GraphQL Version and Health Check cURL Example

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

A cURL command to execute both the version and health check GraphQL queries simultaneously. The output includes the application version, overall health status, details of individual checks, and the startup status of various workers.

```shell
curl -s -X POST http://localhost:3333/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query { version health { status checks { key status error } } workers { listAll { workers { key started } } } }"}' \
  | jq .
# Expected output:
# {
#   "data": {
#     "version": "v0.x.x",
#     "health": { "status": "up", "checks": [...] },
#     "workers": { "listAll": { "workers": [
#       { "key": "http_server", "started": true },
#       { "key": "dht_crawler", "started": true },
#       { "key": "queue_server", "started": true }
#     ]}}
#   }
# }
```

--------------------------------

### Using File Extensions in Conditions

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

An example of an `if_else` action that uses defined file extensions to classify content. If the sum of sizes for files with 'comic' extensions is positive, the content type is set to 'comic'.

```yaml
if_else:
  condition: "torrent.files.map(f, f.extension in extensions.comic ? f.size : - f.size).sum() > 0"
  if_action:
    set_content_type: comic
  else_action: unmatched
```

--------------------------------

### GraphQL Search Torrents Query

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Perform a full-text search for torrents using the `torrentContent.search` GraphQL mutation. This example demonstrates searching for 'Blade Runner' from 1982, with specific filters for content type, resolution, source, language, and ordering by seeders.

```graphql
query SearchMovies {
  torrentContent {
    search(input: {
      queryString: "\"Blade Runner\" 1982"
      limit: 10
      page: 1
      totalCount: true
      hasNextPage: true
      facets: {
        contentType: { filter: [movie] }
        videoResolution: { filter: [V1080p, V2160p], aggregate: true }
        videoSource: { filter: [BluRay], aggregate: true }
        language: { filter: [en], aggregate: true }
        releaseYear: { aggregate: true }
        torrentSource: { aggregate: true }
      }
      orderBy: [{ field: seeders, descending: true }]
    }) {
      totalCount
      totalCountIsEstimate
      hasNextPage
      items {
        id
        infoHash
        contentType
        title
        videoResolution
        videoSource
        videoCodec
        seeders
        leechers
        publishedAt
        torrent {
          name
          size
          magnetUri
          tagNames
          sources { key name seeders leechers }
        }
        content {
          title
          releaseYear
          overview
          voteAverage
          popularity
          externalLinks { metadataSource { name } url }
        }
        languages { id name }
        episodes {
          label
          seasons { season episodes }
        }
      }
      aggregations {
        videoResolution { value label count isEstimate }
        videoSource { value label count isEstimate }
        releaseYear { value label count isEstimate }
        torrentSource { value label count isEstimate }
      }
    }
  }
}
```

--------------------------------

### Conditional Deletion Based on Flags

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Demonstrates how to use a flag within a condition to conditionally perform an action. This example deletes content if the `delete_xxx` flag is true and the content type is 'xxx'.

```yaml
if_else:
  condition: "flags.delete_xxx && result.contentType == contentType.xxx"
  if_action: delete
```

--------------------------------

### Upgrade Bitmagnet with Docker Compose

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/installation.md

Commands to update your Bitmagnet installation to the latest version using Docker Compose. This involves stopping the current container, pulling the new image, and restarting the container.

```sh
docker compose down bitmagnet
docker pull ghcr.io/bitmagnet-io/bitmagnet:latest
docker compose up -d bitmagnet

```

--------------------------------

### Show All Configuration Options CLI

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/configuration.md

Use this command to display all available configuration parameters, their types, current values, default values, and their source.

```sh
bitmagnet config show
```

--------------------------------

### Show Bitmagnet CLI Help

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/setup/installation.md

Displays the help information for the Bitmagnet command-line interface. This is useful for understanding available commands and options.

```sh
bitmagnet --help

```

--------------------------------

### Profile with pprof

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/observability-telemetry.md

Use the Go pprof tool to analyze heap profiles from bitmagnet's profiling endpoints. Ensure bitmagnet is running and accessible.

```sh
go tool pprof http://localhost:3333/debug/pprof/heap
```

--------------------------------

### Profile Bitmagnet Application with Go pprof

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Analyze application performance using Go's pprof tool. Connect to the `/debug/pprof/*` endpoints to collect heap or CPU profiles.

```sh
# Go heap profile
go tool pprof http://localhost:3333/debug/pprof/heap

# CPU profile (30-second sample)
go tool pprof http://localhost:3333/debug/pprof/profile?seconds=30

```

--------------------------------

### Restore or Merge Bitmagnet Database with psql

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Import a `pg_dump` backup file into a target Bitmagnet instance. Ensure the target instance is running the same version and has applied migrations.

```sh
# Restore / merge into a target instance
# (target must be running the same version and have migrations applied)
psql --host=target-host --username=postgres bitmagnet < backup.sql

```

--------------------------------

### Build Project

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/README.md

Builds the Angular project for production. Artifacts are stored in the dist/ directory.

```bash
ng build
```

--------------------------------

### Importing Data via Command Line

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/import.md

This command imports data from a SQLite database into Bitmagnet. It first queries the database using a SQL script, then processes the JSON output with `jq` to add source information and clean up fields, and finally sends the data to the Bitmagnet import endpoint using `curl`.

```sh
sqlite3 -json -batch /path/to/your/rarbg_db.sqlite "$(cat rarbg-import.sql)" \
  | jq -r --indent 0 '.[] | . * { source: "rarbg" } | . + if .imdb != null then { contentSource: "imdb", contentId: .imdb } else {} end | del(.imdb) | del(..|nulls)' \
  | curl --verbose -H "Content-Type: application/json" -H "Connection: close" --data-binary @- http://localhost:3333/import
```

--------------------------------

### Restore or Merge Bitmagnet Database Backup

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/backup-restore-merge.md

Import a backup file into a target Bitmagnet database using psql. Ensure the target instance is running and is the same version as the source. Refer to psql documentation for host, username, and password specifics.

```sh
psql bitmagnet < backup.sql
```

--------------------------------

### Order By Options in Queue Jobs

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/dashboard/queue/queue-jobs.component.html

Displays sorting options for queue jobs, including labels and an indicator for ascending or descending order. Iterates through predefined options.

```html
{{ t("torrents.order_by") }} @for (option of orderByOptions; track option.field) { {{ t("dashboard.queues." + option.field) }} } {{ controls.orderBy.descending ? "arrow_downward" : "arrow_upward" }}
```

--------------------------------

### Add Observability Stack to Docker Compose

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Integrate Grafana, Prometheus, Loki, and Pyroscope into your `docker-compose.yml` for comprehensive observability.

```yaml
# Add to docker-compose.yml for full observability
  grafana:
    image: grafana/grafana:latest
    ports: ["3000:3000"]

  prometheus:
    image: prom/prometheus:latest
    volumes: ["./observability/prometheus.yml:/etc/prometheus/prometheus.yml"]

  loki:
    image: grafana/loki:latest

  pyroscope:
    image: pyroscope/pyroscope:latest

```

--------------------------------

### Import Torrents via POST /import Endpoint

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Ingest torrents from any source by sending a newline-delimited JSON stream to the /import endpoint. This is useful for bulk loading datasets like RARBG backups.

```sh
# Minimal single-torrent import
echo '{"infoHash":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","name":"My Movie (2023)","size":8589934592,"source":"manual","contentType":"movie","publishedAt":"2023-06-15T00:00:00.000Z"}' \
  | curl -s -X POST http://localhost:3333/import \
    -H "Content-Type: application/json" \
    --data-binary @-
```

```sh
# Import from RARBG SQLite backup
# rarbg-import.sql extracts: hash, title, size, content type, resolution, source, codec, IMDB id
sqlite3 -json -batch /path/to/rarbg_db.sqlite "$(cat rarbg-import.sql)" \
  | jq -r --indent 0 \
    '.[] | . * { source: "rarbg" }
         | . + if .imdb != null then { contentSource: "imdb", contentId: .imdb } else {} end
         | del(.imdb)
         | del(..|nulls)' \
  | curl --verbose \
      -H "Content-Type: application/json" \
      -H "Connection: close" \
      --data-binary @- \
      http://localhost:3333/import
```

--------------------------------

### Backup Bitmagnet Database with pg_dump

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Export all critical Bitmagnet tables' data only (no schema) using `pg_dump`. This creates portable backups compatible with the same Bitmagnet version.

```sh
# Backup — export all critical bitmagnet tables (data only, no schema)
pg_dump \
  --host=localhost --username=postgres \
  --column-inserts \
  --data-only \
  --on-conflict-do-nothing \
  --rows-per-insert=1000 \
  --table=metadata_sources \
  --table=content \
  --table=content_attributes \
  --table=content_collections \
  --table=content_collections_content \
  --table=torrent_sources \
  --table=torrents \
  --table=torrent_files \
  --table=torrent_hints \
  --table=torrent_contents \
  --table=torrent_tags \
  --table=torrents_torrent_sources \
  --table=key_values \
  bitmagnet > backup.sql

```

--------------------------------

### Backup Bitmagnet Database Tables

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/backup-restore-merge.md

Use pg_dump to create a data-only backup of specified Bitmagnet tables. Ensure the target instance is the same version if importing to another instance. Refer to pg_dump documentation for host, username, and password specifics.

```sh
pg_dump \
        --column-inserts \
        --data-only \
        --on-conflict-do-nothing \
        --rows-per-insert=1000 \
        --table=metadata_sources \
        --table=content \
        --table=content_attributes \
        --table=content_collections \
        --table=content_collections_content \
        --table=torrent_sources \
        --table=torrents \
        --table=torrent_files \
        --table=torrent_hints \
        --table=torrent_contents \
        --table=torrent_tags \
        --table=torrents_torrent_sources \
        --table=key_values \
        bitmagnet \
        > backup.sql
```

--------------------------------

### Customizing Classifier via Environment Variables

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Shows how to set classifier configurations, such as disabling TMDB integration or specifying a custom workflow, using environment variables before running a worker.

```sh
TMDB_ENABLED=false \
  CLASSIFIER_WORKFLOW=custom \
  CLASSIFIER_DELETE_XXX=true \
  bitmagnet worker run --all
```

--------------------------------

### POST /import

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Bulk-imports torrents from any external source by accepting a newline-delimited JSON stream.

```APIDOC
## POST /import

### Description
Bulk-imports torrents from any external source by accepting a newline-delimited JSON stream. Each object maps to a torrent record, allowing ingestion from external datasets.

### Method
POST

### Endpoint
/import

### Parameters
#### Request Body
- **infoHash** (string) - Required - 40-char SHA1 info hash.
- **name** (string) - Required - Torrent display name.
- **size** (integer) - Total size in bytes.
- **source** (string) - Source label (e.g., "rarbg", "manual").
- **contentType** (string) - Type of content (e.g., `movie`, `tv_show`, `music`).
- **contentSource** (string) - External metadata source (e.g., "imdb", "tmdb").
- **contentId** (string) - External content ID (e.g., IMDB "tt0083658").
- **videoResolution** (string) - Video resolution (e.g., `V720p`, `V1080p`).
- **videoSource** (string) - Video source (e.g., `BluRay`, `WEBDL`).
- **videoCodec** (string) - Video codec (e.g., `x264`, `x265`).
- **publishedAt** (ISO date) - Original publication timestamp.

### Request Example
```sh
# Minimal single-torrent import
echo '{"infoHash":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","name":"My Movie (2023)","size":8589934592,"source":"manual","contentType":"movie","publishedAt":"2023-06-15T00:00:00.000Z"}' \
  | curl -s -X POST http://localhost:3333/import \
    -H "Content-Type: application/json" \
    --data-binary @-
```
```

--------------------------------

### Find Match for Audiobook or Ebook

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Attempts to classify a torrent first as an 'audiobook' and then as an 'ebook'. If both attempts result in an 'unmatched' error, the content type defaults to 'unknown'. This action is useful for handling multiple potential content types.

```yaml
find_match:
  # match audiobooks:
  - if_else:
      condition: "torrent.baseName.matches(keywords.audiobook)"
      if_action:
        set_content_type: audiobook
      else_action: unmatched
  # match ebooks:
  - if_else:
      condition: "torrent.files.map(f, f.extension in extensions.ebook ? f.size : - f.size).sum() > 0"
      if_action:
        set_content_type: ebook
      else_action: unmatched
```

--------------------------------

### Display Sorting Options

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrents-search.component.html

Iterates through sorting options and displays their translated names. The 'relevance' option is only shown if a query string value exists. Includes an icon to indicate the current sort direction (descending/ascending).

```html
{{ t("torrents.order\_by") }} @for (option of orderByOptions; track option.field) { @if (option.field != "relevance" || queryString.value) { {{ t("torrents.ordering." + option.field) }} } } {{ controls.orderBy.descending ? "arrow\_downward" : "arrow\_upward" }}
```

--------------------------------

### Google Analytics Initialization

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/_includes/head_custom.html

Initializes the Google Analytics data layer and configures the tracking ID. This script should be included in the head of the HTML document to ensure proper tracking of website visitors and events.

```javascript
window.dataLayer = window.dataLayer || [];
function gtag() {
  dataLayer.push(arguments);
}
gtag("js", new Date());
gtag("config", "G-J0XY0QVC39");
```

--------------------------------

### Customizing Classifier via config.yml

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Illustrates how to override classifier settings like workflow, keywords, extensions, and flags using the main application configuration file (`config.yml`).

```yaml
classifier:
  workflow: custom
  keywords:
    music:
      - my-custom-music-keyword
  extensions:
    audiobook:
      - abc
  flags:
    delete_content_types:
      - comics
```

--------------------------------

### Run Bitmagnet Worker with Custom Classifier Workflow

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Execute the Bitmagnet worker using a custom classifier workflow by setting the CLASSIFIER_WORKFLOW environment variable or configuring it in `config.yml`.

```sh
# Use the custom workflow instead of the default
CLASSIFIER_WORKFLOW=custom bitmagnet worker run --all

# Or in config.yml:
# classifier:
#   workflow: custom

```

--------------------------------

### Check Bitmagnet Status Endpoint

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Use this command to check the health and status of the Bitmagnet application.

```shell
curl http://localhost:3333/status
```

--------------------------------

### /torznab

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Provides a Torznab-compatible endpoint for integration with Prowlarr, Sonarr, and Radarr.

```APIDOC
## /torznab — Torznab / Servarr Integration

### Description
Exposes a standard Torznab endpoint compatible with Prowlarr, Sonarr, and Radarr. Add it as a "Generic Torznab" indexer in Prowlarr.

### Method
GET

### Endpoint
/torznab

### Parameters
#### Query Parameters
- **t** (string) - Required - Type of request (e.g., `caps` for capabilities, `search` for searching).
- **q** (string) - Optional - Search query string.
- **cat** (integer) - Optional - Category ID for searching.
- **season** (integer) - Optional - Season number for TV show searches.
- **ep** (integer) - Optional - Episode number for TV show searches.

### Request Example
```sh
# Test the Torznab endpoint directly
curl "http://localhost:3333/torznab?t=caps"          # capabilities
curl "http://localhost:3333/torznab?t=search&q=interstellar&cat=2000"  # movie search
curl "http://localhost:3333/torznab?t=tvsearch&q=breaking+bad&season=1&ep=1"
```

### Prowlarr Configuration
1. Open Prowlarr → Settings → Indexers → Add Indexer.
2. Select **Generic Torznab**.
3. Set URL to `http://bitmagnet:3333/torznab` (adjust hostname as needed).
4. Click **Test** to verify connectivity (no API key required).
5. Save the indexer.
```

--------------------------------

### Tag Torrents with Interesting Documents

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Create a custom workflow to tag torrents that contain documents with specific file extensions and keywords in their filenames. This demonstrates advanced conditional logic.

```yaml
extensions:
  interesting_documents:
    - doc
    - docx
    - pdf
keywords:
  interesting_documents:
    - interesting
    - fascinating
workflows:
  custom:
    - run_workflow: default
    - if_else:
        condition: "torrent.files.filter(f, f.extension in extensions.interesting_documents && f.basePath.matches(keywords.interesting_documents)).size() > 0"
        if_action:
          add_tag: interesting-documents
```

--------------------------------

### Defining Keywords for Classification

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Define lists of keywords for different content types. Keywords are case-insensitive by default and are compiled into regular expressions for matching isolated tokens within strings like torrent names.

```yaml
keywords:
  music:
    - music
    - discography
    - album
    - \V.?\A
    - various artists
  audiobook:
    - (audio)?books?
    - (un)?abridged
    - narrated
    - novels?
    - (auto)?biograph(y|ies)
```

--------------------------------

### Set Torrent Tags

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Replaces all existing tags on specified torrents with a new set of tags.

```APIDOC
## MUTATION SetTags

### Description
Replaces all existing tags on specified torrents with a new set of tags.

### Method
MUTATION

### Endpoint
torrent.setTags

### Parameters
#### Arguments
- **infoHashes** (String!)
  - Required
  - List of info hashes for the torrents to update.
- **tagNames** (String!)
  - Required
  - List of tag names to set on the torrents.

### Request Example
```json
{
  "torrent": {
    "setTags": {
      "infoHashes": ["a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"],
      "tagNames": ["archive"]
    }
  }
}
```
```

--------------------------------

### Toggle Drawer Open/Close Icon

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/dashboard/queue/queue-jobs.component.html

Conditionally renders an icon based on the drawer's open state. Uses a ternary operator for concise logic.

```html
{{ drawer.opened ? "arrow_circle_left" : "arrow_circle_right" }}
```

--------------------------------

### GraphQL Mutations for Torrent Management

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Use these GraphQL mutations to manage tags, delete tags, delete torrents, or trigger reprocessing of torrents in Bitmagnet.

```graphql
mutation SetTags {
  torrent {
    setTags(
      infoHashes: ["a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"]
      tagNames: ["archive"]
    )
  }
}
```

```graphql
mutation RemoveTags {
  torrent {
    deleteTags(
      infoHashes: ["a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"]
      tagNames: ["favorites"]
    )
  }
}
```

```graphql
mutation DeleteTorrents {
  torrent {
    delete(infoHashes: [
      "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3"
    ])
  }
}
```

```graphql
mutation ReprocessTorrents {
  torrent {
    reprocess(input: {
      infoHashes: ["a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"]
      classifierRematch: true      # force re-match against content DB
      classifierWorkflow: "custom" # use a specific workflow
      apisDisabled: false          # allow TMDB API calls
      localSearchDisabled: false
    })
  }
}
```

--------------------------------

### File Path Display

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrent-files-table.component.html

Displays the path of a file within the torrent. Uses internationalization for the column header.

```HTML
{{ t("torrents.file_path") }}

{{ item(i).path }}
```

--------------------------------

### GraphQL Version and Health Check Queries

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

GraphQL queries to retrieve the application version and perform a comprehensive health check of all internal workers and subsystems. The health check includes status, timestamps, and error information for each check.

```graphql
# Check version
query GetVersion {
  version
}

# Full health check — lists all subsystem statuses and running workers
query HealthCheck {
  health {
    status          # overall: unknown | inactive | up | down
    checks {
      key
      status
      timestamp
      error
    }
  }
  workers {
    listAll {
      workers {
        key       # e.g. "http_server", "dht_crawler", "queue_server"
        started
      }
    }
  }
}
```

--------------------------------

### Configure Classifier DSL with YAML and CEL

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Define custom classification rules using YAML and CEL expressions. This configuration is loaded from `classifier.yml` and merged with built-in rules.

```yaml
# ~/.config/bitmagnet/classifier.yml
$schema: https://bitmagnet.io/schemas/classifier-0.1.json

# Add keywords to existing lists (merged with core)
keywords:
  music:
    - my-custom-band-name
  banned:
    - unwanted-keyword        # auto-deletes any torrent matching this keyword
  interesting_documents:
    - whitepaper
    - research

# Add file extensions to existing lists
extensions:
  interesting_documents:
    - pdf
    - docx

# Classifier flags (configures built-in behaviour)
flags:
  delete_xxx: true                          # auto-delete adult content
  delete_content_types:                     # auto-delete specific content types
    - software
    - game
  tmdb_enabled: true                        # set false to disable TMDB lookups

# Custom workflow that wraps the default workflow
workflows:
  custom:
    # 1. Delete torrents with banned keywords
    - if_else:
        condition: "torrent.baseName.matches(keywords.banned)"
        if_action: delete

    # 2. Run the built-in default classification logic
    - run_workflow: default

    # 3. Tag torrents containing interesting document files
    - if_else:
        condition: >
          torrent.files
            .filter(f,
              f.extension in extensions.interesting_documents &&
              f.basePath.matches(keywords.interesting_documents)
            ).size() > 0
        if_action:
          add_tag: interesting-documents

    # 4. Custom audiobook detection using boolean logic
    - find_match:
        - if_else:
            condition:
              or:
                - "torrent.baseName.matches(keywords.audiobook)"
                - and:
                    - "torrent.files.map(f, f.extension in extensions.audiobook ? f.size : -f.size).sum() > 0"
                    - "torrent.size > 50 * mb"
            if_action:
              set_content_type: audiobook
            else_action: unmatched

```

--------------------------------

### File Index Display

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrent-files-table.component.html

Displays the index of a file within the torrent. Uses internationalization for the column header.

```HTML
{{ t("torrents.file_index") }}

{{ item(i).index }}
```

--------------------------------

### Iterate and Display Content Types

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrents-search.component.html

Iterates through available content types and displays their icon, translated name, and count. It conditionally renders types that are either 'null' or included in the available content types.

```html
@for (ct of contentTypes; track ct.key) { @if ( ct.key === "null" || (dataSource.availableContentTypes$ | async)?.includes(ct.key) ) {*   {{ ct.icon }} {{ t("content\_types.plural." + ct.key) }} @if ( (dataSource.contentTypeCounts$ | async)?.["ct.key"]; as agg ) { {{ agg.count | intEstimate: agg.isEstimate }} } @else { 0 } }
```

--------------------------------

### Extend Default Workflow with Custom Actions

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Add custom logic to the default classifier workflow by defining custom actions before or after the default processing.

```yaml
workflows:
  custom:
    - <my custom action to be executed before the default workflow>
    - run_workflow: default
    - <my custom action to be executed after the default workflow>
```

--------------------------------

### Display and Edit Torrent Tags

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrent-edit-tags.component.html

Iterates over edited tags, displaying each tag with a cancel action. Also iterates over suggested tags, displaying them for potential addition.

```html
@for (tagName of editedTags; let j = $index; track tagName) { {{ tagName }} cancel }  @for (tagName of suggestedTags; track tagName) { {{ tagName }} }
```

--------------------------------

### Query Bitmagnet Prometheus Metrics

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Fetch and filter Prometheus metrics exposed by Bitmagnet at the `/metrics` endpoint. Useful for monitoring DHT crawler activity and other internal states.

```sh
# Query key DHT crawler metrics
curl -s http://localhost:3333/metrics | grep bitmagnet_dht_crawler_persisted_total
# bitmagnet_dht_crawler_persisted_total{entity="Torrent"} 142857       # newly crawled
# bitmagnet_dht_crawler_persisted_total{entity="TorrentsTorrentSource"} 21000  # rediscovered

# All available bitmagnet metrics
curl -s http://localhost:3333/metrics | grep '^bitmagnet_'

```

--------------------------------

### Toggle Drawer Visibility

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrents-search.component.html

Conditionally displays an icon to indicate whether a drawer is opened or closed.

```html
{{ drawer.opened ? "arrow\_circle\_left" : "arrow\_circle\_right" }}
```

--------------------------------

### Conditional Rendering for Over Threshold Files

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrent-files-table.component.html

Conditionally renders file information when the torrent's file status is 'over_threshold'. Uses internationalization for display.

```HTML
@if (torrent.filesStatus === "over_threshold") {

{{ t("torrents.showing_x_of_y_files", { x: dataSource.result.totalCount | number, y: torrent.filesCount == null ? "?" : (torrent.filesCount | number), }) }}

}
```

--------------------------------

### GraphQL API - Version & Health Check

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Retrieve the application version and check the health status of all internal workers and subsystems. This is useful for monitoring the application's operational state.

```APIDOC
## GraphQL API - Version & Health Check

**`version` and `health` — check application status and worker health**

Retrieve the running application version and the health/startup status of all internal workers and subsystems.

### Request Example
```graphql
# Check version
query GetVersion {
  version
}

# Full health check — lists all subsystem statuses and running workers
query HealthCheck {
  health {
    status          # overall: unknown | inactive | up | down
    checks {
      key
      status
      timestamp
      error
    }
  }
  workers {
    listAll {
      workers {
        key       # e.g. "http_server", "dht_crawler", "queue_server"
        started
      }
    }
  }
}
```

### Curl Example
```sh
curl -s -X POST http://localhost:3333/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"query { version health { status checks { key status error } } workers { listAll { workers { key started } } } }"}' \
  | jq .
```
```

--------------------------------

### Access Prometheus Metrics

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Retrieve Prometheus metrics from Bitmagnet to monitor performance and internal states. The output can be filtered for specific metrics like `bitmagnet_dht_crawler_persisted_total`.

```shell
curl http://localhost:3333/metrics | grep bitmagnet_dht_crawler_persisted_total
```

--------------------------------

### Display Facets and Aggregations

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrents-search.component.html

Iterates through facets, displaying their icon and translated name. It conditionally shows aggregations if they exist, either directly or as a fallback.

```html
@for (facet of facets$ | async; track facet.key) { @if (facet.relevant) { {{ facet.icon }} {{ t("facets." + facet.key) }} @if (facet.filter?.length) { @for (agg of facet.aggregations; track agg.value) { {{ agg.label }} {{ agg.count | intEstimate: agg.isEstimate }} } } @else { @if (facet.aggregations.length) { @for (agg of facet.aggregations; track agg.value) { {{ agg.label }} {{ agg.count | intEstimate: agg.isEstimate }} } } @else { {{ t("general.none") }} } } } }
```

--------------------------------

### GraphQL API - Search Torrents

Source: https://context7.com/bitmagnet-io/bitmagnet/llms.txt

Perform a full-text search for torrent content with faceted filtering. This query allows for detailed searching based on keywords, content type, resolution, source, language, and more, returning matched torrents with rich metadata.

```APIDOC
## GraphQL API - Search Torrents

**`torrentContent.search` — full-text torrent search with faceted filtering**

The primary search query. Accepts a query string, pagination, facets (content type, source, resolution, language, genre, year, etc.), and ordering. Returns matched `TorrentContent` items with rich metadata and optional aggregation counts.

### Request Example
```graphql
# POST http://localhost:3333/graphql
# Content-Type: application/json

query SearchMovies {
  torrentContent {
    search(input: {
      queryString: "\"Blade Runner\" 1982"
      limit: 10
      page: 1
      totalCount: true
      hasNextPage: true
      facets: {
        contentType: { filter: [movie] }
        videoResolution: { filter: [V1080p, V2160p], aggregate: true }
        videoSource: { filter: [BluRay], aggregate: true }
        language: { filter: [en], aggregate: true }
        releaseYear: { aggregate: true }
        torrentSource: { aggregate: true }
      }
      orderBy: [{ field: seeders, descending: true }]
    }) {
      totalCount
      totalCountIsEstimate
      hasNextPage
      items {
        id
        infoHash
        contentType
        title
        videoResolution
        videoSource
        videoCodec
        seeders
        leechers
        publishedAt
        torrent {
          name
          size
          magnetUri
          tagNames
          sources { key name seeders leechers }
        }
        content {
          title
          releaseYear
          overview
          voteAverage
          popularity
          externalLinks { metadataSource { name } url }
        }
        languages { id name }
        episodes {
          label
          seasons { season episodes }
        }
      }
      aggregations {
        videoResolution { value label count isEstimate }
        videoSource { value label count isEstimate }
        releaseYear { value label count isEstimate }
        torrentSource { value label count isEstimate }
      }
    }
  }
}
```

### Curl Example
```sh
curl -s -X POST http://localhost:3333/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { torrentContent { search(input: { queryString: \"blade runner\", limit: 5, facets: { contentType: { filter: [movie] }, videoResolution: { filter: [V1080p] } }, orderBy: [{ field: seeders, descending: true }] }) { totalCount items { title videoResolution seeders torrent { magnetUri } } } } }"'
```
```

--------------------------------

### Conditional Set Content Type or Unmatched

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/bitmagnet.io/guides/classifier.md

Conditionally sets the content type to 'audiobook' if the torrent name matches specified keywords. Otherwise, it returns an 'unmatched' error, allowing for further classification attempts.

```yaml
if_else:
  condition: "torrent.baseName.matches(keywords.audiobook)"
  if_action:
    set_content_type: audiobook
  else_action: unmatched
```

--------------------------------

### File Type Display

Source: https://github.com/bitmagnet-io/bitmagnet/blob/main/webui/src/app/torrents/torrent-files-table.component.html

Displays the type of a file, falling back to 'unknown' if not specified. Uses internationalization for the column header and file type labels.

```HTML
{{ t("torrents.file_type") }}

{{ t("file_types." + (item(i).fileType ?? "unknown")) }}
```