### Torrentool CLI Commands

Source: https://context7.com/idlesign/torrentool/llms.txt

Use these commands to interact with torrentool from the command line. Install with `pip install torrentool[cli]`.

```bash
# Show version
torrentool --version
```

```bash
# Create torrent from a file
torrentool torrent create /path/to/video.mkv
```

```bash
# Create torrent from a directory
torrentool torrent create /path/to/folder/
```

```bash
# Create with specific tracker
torrentool torrent create /path/to/file --tracker "udp://tracker.example.com:6969"
```

```bash
# Create with multiple trackers (comma-separated)
torrentool torrent create /path/to/file --tracker "udp://tracker1.com:6969,udp://tracker2.com:6969"
```

```bash
# Create with open trackers (fetches from remote)
torrentool torrent create /path/to/file --open_trackers
```

```bash
# Create with comment
torrentool torrent create /path/to/file --comment "My awesome release"
```

```bash
# Create and upload to cache service
torrentool torrent create /path/to/file --open_trackers --cache
```

```bash
# Specify output directory
torrentool torrent create /path/to/file --dest /output/directory/
```

```bash
# Print torrent file information
torrentool torrent info /path/to/file.torrent
```

```bash
# Combine options
torrentool torrent create /path/to/files --open_trackers --cache --comment "Release v1.0"
```

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

### Get Open Trackers

Source: https://context7.com/idlesign/torrentool/llms.txt

Retrieve lists of open tracker URLs using `get_open_trackers_from_remote()` or `get_open_trackers_from_local()` as a fallback. These are useful for public torrents.

```python
from torrentool.api import Torrent, get_open_trackers_from_remote, get_open_trackers_from_local

# Get open trackers from remote repository (requires requests)
try:
    trackers = get_open_trackers_from_remote()
except Exception:
    # Fall back to local backup list
    trackers = get_open_trackers_from_local()

# Create a torrent with open trackers
torrent = Torrent.create_from('/path/to/files/')
torrent.announce_urls = trackers
torrent.to_file('/path/to/output.torrent')

print(f"Added {len(trackers)} open trackers")
```

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

### Create and Inspect Torrents via CLI

Source: https://github.com/idlesign/torrentool/blob/master/README.rst

Use the command line interface to generate torrent files from local paths or display information about existing torrents.

```bash
; Make .torrent out of `video.mkv`
$ torrentool torrent create /home/my/files_here/video.mkv

; Make .torrent out of entire `/home/my/files_here` dir,
; and put some open trackers announce URLs into it,
; and publish file on torrent caching service, so it is ready to share.
$ torrentool torrent create /home/my/files_here --open_trackers --cache

; Print out existing file info.
$ torrentool torrent info /home/my/some.torrent
```

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

### Torrentool Exception Handling in Python

Source: https://context7.com/idlesign/torrentool/llms.txt

Demonstrates how to catch specific torrentool exceptions for robust error management in Python applications. Import necessary classes from `torrentool.api` and `torrentool.exceptions`.

```python
from torrentool.api import Torrent, Bencode
from torrentool.exceptions import (
    TorrentoolException,    # Base exception
    TorrentError,           # Torrent-related errors
    BencodeError,           # Base bencode errors
    BencodeDecodingError,   # Decoding failures
    BencodeEncodingError,   # Encoding failures
    RemoteUploadError,      # Cache upload failures
    RemoteDownloadError     # Remote fetch failures
)

# Handle torrent errors
try:
    torrent = Torrent.create_from('/path/to/empty_file')
except TorrentError as e:
    print(f"Cannot create torrent: {e}")
```

```python
# Handle bencode errors
try:
    data = Bencode.decode(b'invalid data')
except BencodeDecodingError as e:
    print(f"Failed to decode: {e}")
```

```python
try:
    Bencode.encode(object())  # Unsupported type
except BencodeEncodingError as e:
    print(f"Failed to encode: {e}")
```

```python
# Catch all torrentool exceptions
try:
    torrent = Torrent.from_file('/nonexistent.torrent')
except TorrentoolException as e:
    print(f"Torrentool error: {e}")
except FileNotFoundError:
    print("File not found")
```

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

### Load Torrent from String

Source: https://context7.com/idlesign/torrentool/llms.txt

Use `Torrent.from_string()` to create a Torrent object from bencoded bytes. This is useful for data received over a network or from file contents.

```python
from torrentool.api import Torrent

# Load torrent from bencoded bytes (e.g., from HTTP response)
torrent_data = b'd8:announce35:udp://tracker.example.com:69694:infod...'
torrent = Torrent.from_string(torrent_data)

print(f"Loaded torrent: {torrent.name}")
print(f"Info hash: {torrent.info_hash}")

# Example with requests library
import requests
response = requests.get('http://example.com/file.torrent')
torrent = Torrent.from_string(response.content)
```

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

### Generate Magnet Links

Source: https://context7.com/idlesign/torrentool/llms.txt

Create magnet links with varying levels of detail, including trackers and webseeds.

```python
from torrentool.api import Torrent

torrent = Torrent.from_file('/path/to/file.torrent')

# Basic magnet link (just info hash)
basic_magnet = torrent.magnet_link
# Output: magnet:?xt=urn:btih:a1b2c3d4e5f6...

# Detailed magnet link with trackers and webseeds
detailed_magnet = torrent.get_magnet(detailed=True)
# Output: magnet:?xt=urn:btih:a1b2c3d4...&tr=udp://tracker.example.com:6969&ws=http://webseed.example.com/file

# Custom magnet with specific parameters
magnet_with_trackers = torrent.get_magnet(detailed=['tr'])  # Only trackers
magnet_with_webseeds = torrent.get_magnet(detailed=['ws'])  # Only webseeds
magnet_full = torrent.get_magnet(detailed=['tr', 'ws'])     # Both
```

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

### Create New Torrent Files

Source: https://context7.com/idlesign/torrentool/llms.txt

Generate a new torrent object from a file or directory path and configure trackers, webseeds, and metadata before saving.

```python
from torrentool.api import Torrent

# Create torrent from a single file
torrent = Torrent.create_from('/home/user/video.mkv')

# Or create from a directory (includes all files recursively)
torrent = Torrent.create_from('/home/user/my_folder/')

# Set tracker announce URLs (single or multiple)
torrent.announce_urls = 'udp://tracker.openbittorrent.com:80'

# Or set multiple trackers
torrent.announce_urls = [
    'udp://tracker.openbittorrent.com:80',
    'udp://tracker.opentrackr.org:1337',
    'udp://tracker.coppersurfer.tk:6969'
]

# Set optional metadata
torrent.comment = 'My awesome torrent'
torrent.private = True  # For private trackers

# Add webseeds for HTTP-based downloading
torrent.webseeds = ['http://example.com/files/video.mkv']

# Save to file
torrent.to_file('/home/user/my_torrent.torrent')

# Or get as bytes
torrent_bytes = torrent.to_string()
```

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

### Read Torrent Metadata

Source: https://context7.com/idlesign/torrentool/llms.txt

Load an existing .torrent file to access metadata like info hashes, file lists, and tracker URLs.

```python
from torrentool.api import Torrent

# Load an existing torrent file
my_torrent = Torrent.from_file('/path/to/some.torrent')

# Access basic torrent information
print(f"Name: {my_torrent.name}")
print(f"Total size: {my_torrent.total_size} bytes")
print(f"Info hash: {my_torrent.info_hash}")
print(f"Created by: {my_torrent.created_by}")
print(f"Creation date: {my_torrent.creation_date}")
print(f"Comment: {my_torrent.comment}")
print(f"Private: {my_torrent.private}")

# List all files in the torrent
for file in my_torrent.files:
    print(f"  {file.name}: {file.length} bytes")

# Get tracker URLs
for tracker_list in my_torrent.announce_urls:
    for tracker in tracker_list:
        print(f"Tracker: {tracker}")

# Generate magnet link
print(f"Magnet link: {my_torrent.magnet_link}")
```

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

### Upload Torrent to Cache Server

Source: https://context7.com/idlesign/torrentool/llms.txt

Use `upload_to_cache_server()` to upload a `.torrent` file to a cache service and obtain a download URL. Handles potential `RemoteUploadError` exceptions.

```python
from torrentool.api import Torrent, upload_to_cache_server
from torrentool.exceptions import RemoteUploadError

# Create and save a torrent
torrent = Torrent.create_from('/path/to/my_files/')
torrent.announce_urls = ['udp://tracker.opentrackr.org:1337']
torrent_path = '/tmp/my_files.torrent'
torrent.to_file(torrent_path)

# Upload to cache server (requires requests)
try:
    cache_url = upload_to_cache_server(torrent_path)
    print(f"Torrent cached at: {cache_url}")
except RemoteUploadError as e:
    print(f"Upload failed: {e}")
```

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

### Manage Torrents Programmatically

Source: https://github.com/idlesign/torrentool/blob/master/README.rst

Use the Torrent API to load, modify, and save torrent files, or create new ones from local file systems.

```python
from torrentool.api import Torrent

# Reading and modifying an existing file.
my_torrent = Torrent.from_file('/home/idle/some.torrent')
my_torrent.total_size  # Total files size in bytes.
my_torrent.magnet_link  # Magnet link for you.
my_torrent.comment = 'Your torrents are mine.'  # Set a comment.
my_torrent.to_file()  # Save changes.

# Or we can create a new torrent from a directory.
new_torrent = Torrent.create_from('/home/idle/my_stuff/')  # or it could have been a single file
new_torrent.announce_urls = 'udp://tracker.openbittorrent.com:80'
new_torrent.to_file('/home/idle/another.torrent')
```

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

### Read Bencoded Data from File or String

Source: https://context7.com/idlesign/torrentool/llms.txt

Convenient methods `Bencode.read_file()` and `Bencode.read_string()` simplify decoding bencoded data from files or string/bytes inputs.

```python
from torrentool.api import Bencode

# Read and decode a bencoded file
data = Bencode.read_file('/path/to/file.torrent', byte_keys={'pieces'})
print(data['info']['name'])
print(data['announce'])

# Read from string (accepts both str and bytes)
bencoded_string = b'd4:name5:hello3:numi42ee'
data = Bencode.read_string(bencoded_string)
# Output: {'name': 'hello', 'num': 42}

# Also works with regular strings
data = Bencode.read_string('d4:name5:hello3:numi42ee')
```

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

### Decode Data with Bencode

Source: https://context7.com/idlesign/torrentool/llms.txt

Use `Bencode.decode()` to convert bencoded bytes back into Python objects. The `byte_keys` parameter can be used to retain specific dictionary values as bytes.

```python
from torrentool.api import Bencode

# Decode a simple string
result = Bencode.decode(b'5:hello')
# Output: 'hello'

# Decode an integer
result = Bencode.decode(b'i42e')
# Output: 42

# Decode a list
result = Bencode.decode(b'l4:spam4:eggsi123ee')
# Output: ['spam', 'eggs', 123]

# Decode a dictionary
result = Bencode.decode(b'd4:name7:example6:lengthi1024ee')
# Output: {'length': 1024, 'name': 'example'}

# Decode with byte_keys for binary data (like piece hashes)
torrent_data = b'd4:infod6:pieces20:\x01\x02\x03...4:name8:test.txtee'
result = Bencode.decode(torrent_data, byte_keys={'pieces'})
# 'pieces' value remains as bytes, other strings are decoded to str
```

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

### Encode Data with Bencode

Source: https://context7.com/idlesign/torrentool/llms.txt

The `Bencode.encode()` method converts Python objects into bencoded format. Keys in dictionaries are automatically sorted before encoding.

```python
from torrentool.api import Bencode

# Encode a string
encoded_str = Bencode.encode('hello')
# Output: b'5:hello'

# Encode an integer
encoded_int = Bencode.encode(42)
# Output: b'i42e'

# Encode a list
encoded_list = Bencode.encode(['spam', 'eggs', 123])
# Output: b'l4:spam4:eggsi123ee'

# Encode a dictionary (keys are automatically sorted)
encoded_dict = Bencode.encode({
    'name': 'example',
    'length': 1024,
    'files': ['file1.txt', 'file2.txt']
})
# Output: b'd5:filesl9:file1.txt9:file2.txte6:lengthi1024e4:name7:examplee'

# Encode bytes/bytearray
encoded_bytes = Bencode.encode(b'\x00\x01\x02\x03')
# Output: b'4:\x00\x01\x02\x03'

# Encode nested structures
complex_data = {
    'announce': 'http://tracker.example.com',
    'info': {
        'name': 'myfile.txt',
        'length': 12345,
        'piece length': 262144,
        'pieces': b'\x01\x02\x03...'
    }
}
encoded = Bencode.encode(complex_data)
```

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

### Modify Existing Torrent Metadata

Source: https://context7.com/idlesign/torrentool/llms.txt

Update properties of a loaded torrent object and save the changes to the filesystem.

```python
from torrentool.api import Torrent
from datetime import datetime

# Load existing torrent
my_torrent = Torrent.from_file('/path/to/existing.torrent')

# Modify comment
my_torrent.comment = 'Updated comment'

# Change name
my_torrent.name = 'New Torrent Name'

# Update trackers
my_torrent.announce_urls = [
    ['udp://primary-tracker.com:6969'],
    ['udp://backup-tracker.com:6969']  # Backup tracker tier
]

# Set source tag (used by private trackers)
my_torrent.source = 'MyPrivateTracker'

# Update creation date
my_torrent.creation_date = datetime.utcnow()

# Mark as private (disables DHT/PEX)
my_torrent.private = True

# Add HTTP seeds
my_torrent.httpseeds = ['http://seed1.example.com/file', 'http://seed2.example.com/file']

# Save changes to original file
my_torrent.to_file()

# Or save to a new file
my_torrent.to_file('/path/to/modified.torrent')
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.