8000
Skip to content

TAG_SYSTEM.md

Latest commit

 

History

History
353 lines (238 loc) · 9.74 KB

TAG_SYSTEM.md

File metadata and controls

353 lines (238 loc) · 9.74 KB
Raw

Tag System Guide

Complete guide to PrunArr's tag system for user tracking and content organization.

Table of Contents

Overview

PrunArr uses tags in Radarr/Sonarr for two purposes:

  1. User Tracking - Associate content with specific users for removal
  2. Content Organization - Filter and manage content by categories (4K, HDR, Kids, etc.)

User Tags (Required for Removal)

Format: "userid - username" (e.g., "123 - john_doe")

User tags tell PrunArr:

  • Who requested this content
  • Who should be able to remove it
  • Which Tautulli user to match for watch status

Important Rules:

  • Only movies/shows with user tags are processed for removal
  • The username must match a user in Tautulli
  • Content is only removed when watched by the user specified in the tag
  • Pattern is configurable via user_tag_regex in config (default: ^\d+ - (.+)$)

Automatic Tags with Overseerr (Recommended)

The easiest way to set up user tags is with Overseerr's "Tag Requests" feature!

Overseerr can automatically add user tags to Radarr/Sonarr when users request content. This means PrunArr will automatically know who requested what, and only remove content watched by the original requester.

Setup in Overseerr

  1. Open Overseerr web interface
  2. Go to Settings → Radarr (or Sonarr)
  3. Edit your Radarr/Sonarr server configuration
  4. Enable "Tag Requests"
  5. Save settings

That's it! Now when users request movies or shows through Overseerr:

  • Overseerr automatically creates a tag like "123 - john_doe"
  • The tag is added to the content in Radarr/Sonarr
  • PrunArr can match the username with Tautulli users
  • Content is only removed when watched by the original requester

Benefits

  • ✅ No manual tag management needed
  • ✅ Perfect for multi-user Plex servers
  • ✅ Ensures users only affect their own requested content
  • ✅ Works automatically for all new requests
  • ✅ Integrates seamlessly with PrunArr's default configuration

How It Works

  1. User requests content in Overseerr (e.g., user "alice" requests "The Matrix")
  2. Overseerr creates tag in format "123 - alice" (where 123 is the user's ID)
  3. Content is added to Radarr/Sonarr with the user tag
  4. User watches content tracked by Tautulli
  5. PrunArr matches the tag username ("alice") with Tautulli username
  6. Content is removed only when alice has watched it for the configured period

Manual User Tags

If you're not using Overseerr, you can manually create tags in Radarr/Sonarr.

Creating Manual Tags

  1. In Radarr/Sonarr, go to Settings → Tags
  2. Create tags following the pattern: "123 - john_doe", "456 - alice", etc.
    • The number can be any ID (doesn't have to be a real user ID)
    • The username after the dash must match the username in Tautulli
  3. Assign tags to movies/series when adding or editing them
  4. Verify the username matches exactly with Tautulli usernames

Example Manual Tags

123 - john_doe
456 - alice
789 - bob
100 - family_account

Each content item should have one user tag indicating who requested it.

Custom Tag Patterns

You can customize the user tag pattern in config.yaml if you have a different tagging scheme:

# Default pattern (works with Overseerr)
user_tag_regex: "^\\d+ - (.+)$"

# Custom patterns:
user_tag_regex: "^user:(.+)$"           # For tags like "user:john_doe"
user_tag_regex: "^\\[(.+)\\]$"          # For tags like "[john_doe]"
user_tag_regex: "^req_by_(.+)$"         # For tags like "req_by_alice"
user_tag_regex: "^(.+)@.+$"             # For tags like "john@family"

Pattern Requirements:

  • Must be a valid regex pattern
  • Must have exactly one capture group () that extracts the username
  • The extracted username must match a username in Tautulli

Testing Your Pattern:

# Enable debug mode to see how tags are parsed
prunarr --debug movies list --limit 5

Organizational Tags

Examples: "4K", "HDR", "Kids", "Action", "Documentary"

These are regular tags that don't match the user tag pattern. Use them to organize and filter content by categories, quality, genre, etc.

Common Organizational Tags

  • Quality: 4K, HDR, 1080p, REMUX
  • Genre: Action, Drama, Comedy, Horror, Sci-Fi
  • Audience: Kids, Family, Adults
  • Source: Bluray, WEB-DL, HDTV
  • Status: Favorites, Must-Keep, Temporary

Creating Organizational Tags

  1. In Radarr/Sonarr, go to Settings → Tags
  2. Create tags for your organizational system
  3. Assign tags to content as needed
  4. Use tags for filtering in PrunArr

Tag Filtering

PrunArr supports powerful tag-based filtering for both user tags and organizational tags.

Basic Tag Filtering

# Include only items with specific tag
prunarr movies list --tag "4K"

# Exclude items with specific tag
prunarr movies list --exclude-tag "Kids"

# Combine include and exclude
prunarr movies list --tag "Action" --exclude-tag "Kids"

Multiple Tags (OR Logic)

By default, multiple --tag options use OR logic (item has at least one tag):

# Show movies with Action OR Sci-Fi tag
prunarr movies list --tag "Action" --tag "Sci-Fi"

# Show series with Drama OR Thriller tag
prunarr series list --tag "Drama" --tag "Thriller"

Multiple Tags (AND Logic)

Use --tag-match-all to require ALL specified tags:

# Show movies with BOTH 4K AND HDR tags
prunarr movies list --tag "4K" --tag "HDR" --tag-match-all

# Show series with BOTH Drama AND HBO tags
prunarr series list --tag "Drama" --tag "HBO" --tag-match-all

Complex Tag Filters

# 4K movies that are NOT kids content
prunarr movies list --tag "4K" --exclude-tag "Kids"

# Action or Sci-Fi movies, but not kids content
prunarr movies list --tag "Action" --tag "Sci-Fi" --exclude-tag "Kids"

# Movies with BOTH 4K and HDR, excluding favorites
prunarr movies list --tag "4K" --tag "HDR" --tag-match-all --exclude-tag "Favorites"

Tag Filtering in Remove Commands

All tag filters work in remove commands:

# Remove kids content after 2 weeks
prunarr movies remove --watched --tag "Kids" --days-watched 14

# Remove 4K content after 90 days (keep longer due to quality)
prunarr movies remove --watched --tag "4K" --days-watched 90

# Remove content without favorite tag after 60 days
prunarr movies remove --watched --exclude-tag "Favorites" --days-watched 60

Tag Display

In List Commands

  • User tags are shown in the "User" column
  • Organizational tags are shown in the "Tags" column
  • Maximum of 3 tags displayed, with "+N more" if there are additional tags
  • Tag matching is case-insensitive

Example Output

Title                User        Tags                Status
─────────────────────────────────────────────────────────────
The Matrix           john_doe    4K, HDR            Watched
Toy Story            alice       Kids, Family       Watched
Breaking Bad         bob         Drama, Crime, +1   Partial

Best Practices

1. Use Overseerr for User Tags

If you have Overseerr, enable "Tag Requests" for automatic user tag management.

2. Consistent Organizational Tags

Create a standard set of organizational tags and use them consistently:

  • Quality tags: 4K, HDR, 1080p
  • Genre tags: Action, Drama, Comedy, etc.
  • Audience tags: Kids, Family, Adults

3. Keep User Tags Clean

  • One user tag per content item
  • Username must match Tautulli exactly
  • Don't reuse user tags for organizational purposes

4. Test Your Tag System

Before removing content, verify tags are working:

# List content by user to verify tags
prunarr movies list --username "alice"

# Check that organizational tags work
prunarr movies list --tag "4K"

5. Document Your Tag Scheme

Keep a document of your tag meanings for consistency across your team.

Troubleshooting

Content Not Being Removed

Problem: Movies/series aren't being removed even though they're watched.

Possible Causes:

  1. No user tag on the content
  2. Username in tag doesn't match Tautulli username
  3. Content watched by different user than requester

Solution:

# Check if content has user tags
prunarr --debug movies list | grep "tag"

# Verify usernames match between tags and Tautulli
prunarr history list --username "alice"

Tag Pattern Not Matching

Problem: Tags aren't being recognized.

Solution:

# Enable debug to see how tags are parsed
prunarr --debug movies list --limit 5

# Verify your regex pattern in config
# Test pattern at: https://regex101.com/

Multiple User Tags

Problem: Content has multiple user tags.

Solution: PrunArr uses the first matching user tag. Remove extra user tags from content in Radarr/Sonarr.

Examples

Complete Workflow with Tags

# 1. List content by user (verify tags work)
prunarr movies list --username "alice"

# 2. List content by organizational tag
prunarr movies list --tag "4K"

# 3. Combine filters
prunarr movies list --username "alice" --tag "4K" --watched

# 4. Remove with tag filters
prunarr movies remove --watched --tag "Kids" --days-watched 14 --dry-run

# 5. Remove excluding favorites
prunarr movies remove --watched --exclude-tag "Favorites" --days-watched 60

← Back to README | Next: Streaming Integration →
0