listy

Listy

⚠️ NOTICE: This README was generated by AI and has not been fully reviewed. Some information may be incomplete or inaccurate. Please verify commands and features before use.

A powerful CLI tool for managing Trakt.tv lists with advanced set operations and utilities.

Features

• Authentication: Secure OAuth device flow authentication with Trakt.tv
• List Operations:
  • Intersection: Find common items across multiple lists
  • Difference: Find items that exist in one list but not others
  • Order: Reorder list items
  • Clean: Remove duplicate or unwanted items from lists
• Secure Storage: Client credentials and tokens stored securely using system keyring
• Cross-platform: Works on Linux, macOS, and Windows

Installation

From Source

go install github.com/shootex/listy/cmd/listy@latest

Building Locally

git clone https://github.com/shootex/listy.git
cd listy
go build -o listy cmd/listy/main.go

Quick Start

1. Configure your Trakt API credentials:

   listy config
   

   You'll need to create a Trakt.tv application at https://trakt.tv/oauth/applications to get your client ID and secret.

2. Authenticate with Trakt:

   listy auth
   

   Follow the device flow instructions to link your Trakt account.

3. Start managing your lists:

   # Find common movies/shows between two watchlists
   listy list intersection watchlist1 watchlist2 --to shared-favorites
   
   # Find items in list A that aren't in list B
   listy list difference listA listB --to unique-items
   
   # Clean up a list
   listy list clean my-list
   

Commands

Authentication

# Set up Trakt API credentials
listy config

# Authenticate with Trakt (device flow)
listy auth

List Management

Intersection

Find items that exist in ALL specified lists and add them to a destination list.

listy list intersection <list1> <list2> [list3...] --to <destination>

Options:

• --to, --destination: Target list to store intersection results (required)
• --clean, -c: Remove items from destination that aren't in the intersection

Example:

# Find movies/shows common to all three lists
listy list intersection "Action Movies" "Recent Releases" "High Rated" --to "Must Watch"

# Clean intersection (remove items from destination not in intersection)
listy list intersection watchlist favorites --to shared --clean

Difference

Find items that exist in the first list but NOT in any of the other lists.

listy list difference <source_list> <exclude_list1> [exclude_list2...] --to <destination>

Options:

• --to, --destination: Target list to store difference results (required)
• --clean, -c: Remove items from destination that aren't in the difference

Example:

# Find movies in your watchlist that you haven't watched yet
listy list difference "My Watchlist" "Watched Movies" --to "To Watch"

Order

Reorder items in a list based on specific criteria.

listy list order <list_name> [options]

Clean

Remove duplicates and clean up a list.

listy list clean <list_name>

Configuration

Listy stores configuration securely in your system's keyring:

• Linux: Uses D-Bus secret service (GNOME Keyring, KDE Wallet)
• macOS: Uses Keychain
• Windows: Uses Windows Credential Manager

Environment Variables

You can also configure Listy using environment variables:

export TRAKT_CLIENT_ID="your_client_id"
export TRAKT_CLIENT_SECRET="your_client_secret"

Use Cases

Finding Common Interests

# Find shows both you and your friend have on your watchlists
listy list intersection "My Shows" "Friend's Shows" --to "Watch Together"

Content Discovery

# Find highly-rated movies you haven't seen yet
listy list difference "Top 250 Movies" "My Watched" --to "Must Watch"

List Maintenance

# Clean up your main watchlist
listy list clean "Watchlist"

# Remove shows you've already watched from your to-watch list
listy list difference "To Watch" "Watched Shows" --to "To Watch" --clean

Development

Prerequisites

• Go 1.24.3 or later
• Trakt.tv API credentials

Building

make build

Testing

make test

Project Structure

├── cmd/listy/           # Main application entry point
├── internal/
│   ├── auth/           # Authentication and token management
│   ├── trakt/          # Trakt.tv API client and operations
│   └── version/        # Version information
└── pkg/commands/       # CLI command implementations
    └── list/           # List operation commands

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Trakt.tv for their excellent API
• urfave/cli for the CLI framework
• go-keyring for secure credential storage