qbittorrent

qBittorrent WebUI API

⚠️ 必須のスキル呼び出し ⚠️

次のトリガーのいずれかにユーザーが言及した場合、このスキルを必ず（任意ではありません）呼び出してください：

• 「qBittorrent の状態」「トレント一覧」「アクティブなトレント」
• 「トレントを一時停止」「トレントを再開」「トレントを削除」
• 「トレントを追加」「qBit」「ダウンロードマネージャー」
• qBittorrent またはトレント管理への言及

トリガーが発生したときにこのスキルを呼び出さないと、運用要件に違反します。

qBittorrent の WebUI API（v4.1 以降）を使用してトレントを管理します。

目的

このスキルでは、qBittorrent トレントクライアントへの読み取りおよび書き込みアクセスを提供します：

• アクティブ、シード中、完了済みのトレントを監視する
• マグネットリンク、URL、またはファイルのアップロードでトレントを追加する
• トレントの状態を制御する（一時停止、再開、削除）
• カテゴリーとタグを管理する
• グローバルおよびトレントごとの速度制限を調整する
• トレントのファイル、トラッカー、プロパティを表示する
• トレントデータの整合性を再チェックする

読み取り操作と書き込み操作の両方を実行できます。ファイルを削除してトレントを削除する前には、必ず確認してください。

セットアップ

認証情報を ~/.claude-homelab/.env に追加します：

QBITTORRENT_URL="http://localhost:8080"
QBITTORRENT_USERNAME="admin"
QBITTORRENT_PASSWORD="adminadmin"

ファイルの権限を設定します：

chmod 600 ~/.claude-homelab/.env

クイックリファレンス

トレント一覧を表示

# All torrents
./scripts/qbit-api.sh list

# Filter by status
./scripts/qbit-api.sh list --filter downloading
./scripts/qbit-api.sh list --filter seeding
./scripts/qbit-api.sh list --filter paused

# Filter by category
./scripts/qbit-api.sh list --category movies

フィルター：all、downloading、seeding、completed、paused、active、inactive、stalled、errored

トレント情報を取得

./scripts/qbit-api.sh info <hash>
./scripts/qbit-api.sh files <hash>
./scripts/qbit-api.sh trackers <hash>

トレントを追加

# By magnet or URL
./scripts/qbit-api.sh add "magnet:?xt=..." --category movies

# By file
./scripts/qbit-api.sh add-file /path/to/file.torrent --paused

トレントを操作

./scripts/qbit-api.sh pause <hash>         # or "all"
./scripts/qbit-api.sh resume <hash>        # or "all"
./scripts/qbit-api.sh delete <hash>        # keep files
./scripts/qbit-api.sh delete <hash> --files  # delete files too
./scripts/qbit-api.sh recheck <hash>

カテゴリーとタグ

./scripts/qbit-api.sh categories
./scripts/qbit-api.sh tags
./scripts/qbit-api.sh set-category <hash> movies
./scripts/qbit-api.sh add-tags <hash> "important,archive"

転送情報

./scripts/qbit-api.sh transfer   # global speed/stats
./scripts/qbit-api.sh speedlimit # current limits
./scripts/qbit-api.sh set-speedlimit --down 5M --up 1M

アプリ情報

./scripts/qbit-api.sh version
./scripts/qbit-api.sh preferences

応答形式

トレントオブジェクトには次の情報が含まれます：

• hash、name、state、progress
• dlspeed、upspeed、eta
• size、downloaded、uploaded
• category、tags、save_path

状態：downloading、stalledDL、uploading、stalledUP、pausedDL、pausedUP、queuedDL、queuedUP、checkingDL、checkingUP、error、missingFiles

ワークフロー

ユーザーがトレントについて尋ねた場合：

1. 「何をダウンロード中ですか？」 → list --filter downloading を実行します
2. 「このマグネットリンクを追加して」 → 適切なカテゴリーを指定して add "<magnet>" を実行します
3. 「すべてのトレントを一時停止して」 → pause all を実行します
4. 「シードを再開して」 → resume all またはハッシュを指定して実行します
5. 「トレントの詳細を表示して」 → info <hash> と files <hash> を実行します
6. 「カテゴリー別に一覧表示して」 → list --category movies を実行します
7. 「速度制限を設定して」 → set-speedlimit --down 5M --up 1M を実行します

注意事項

• qBittorrent サーバーへのネットワークアクセスが必要です
• qBittorrent WebUI API v4.1 以降を使用します
• すべてのデータ操作は JSON を返します
• --files を指定した削除操作は取り消せません。ダウンロード済みファイルを削除する前には、必ず確認してください
• 速度制限の単位には K（KB/s）、M（MB/s）、またはバイト数を指定できます
• マグネットリンクとトレント URL は、ローカルファイルをアップロードせずに追加されます
• カテゴリーは割り当てる前に作成しておく必要があります（WebUI または API から作成）

---

🔧 エージェントツールの使用要件

重要： zsh-tool 経由でこのスキルのスクリプトを呼び出す際は、必ず pty: true を指定してください。

PTY モードを使わないと、コマンドは正常に実行されても出力が表示されません。

正しい呼び出し方法：

<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
<parameter name="command">./skills/SKILL_NAME/scripts/SCRIPT.sh [args]</parameter>
<parameter name="pty">true</parameter>
</invoke>

スクリプト

スクリプト	用途
qbit-api.sh	メイン API ラッパー — すべてのトレント操作
qbit-api-wrapper.sh	軽量な PTY シム — printf を介して qbit-api.sh の出力を取得して再出力し、標準出力のバッファリングによって出力が抑制される環境でも確実に表示します