### Start rqbit Server

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Starts the rqbit server, specifying the download directory. This is a basic command to get the server running.

```bash
rqbit server start ~/Downloads
```

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

### Start Dev Server

Source: https://github.com/ikatson/rqbit/blob/main/DEV-GUIDE.md

Starts the development server for the project.

```bash
make devserver
```

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

### Install Web UI Dependencies

Source: https://github.com/ikatson/rqbit/blob/main/DEV-GUIDE.md

Installs the necessary dependencies for the Web UI.

```bash
make webui-deps
```

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

### Install Web UI Dependencies

Source: https://github.com/ikatson/rqbit/blob/main/desktop/README.md

Installs the necessary Node.js dependencies for the rqbit web UI. Run this in the webui directory.

```bash
npm install
```

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

### Run Web UI Development

Source: https://github.com/ikatson/rqbit/blob/main/DEV-GUIDE.md

Starts the development server specifically for the Web UI.

```bash
make webui-dev
```

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

### Install rqbit with Homebrew

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Installs the rqbit client on macOS or Linux systems that use Homebrew package manager.

```bash
brew install rqbit
```

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

### Run Tauri Development

Source: https://github.com/ikatson/rqbit/blob/main/DEV-GUIDE.md

Starts the development environment for the desktop application using Tauri.

```bash
cargo tauri dev
```

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

### Install rqbit with Cargo

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Installs the rqbit client using Cargo, the Rust package manager. Requires the Rust toolchain to be installed.

```bash
cargo install rqbit
```

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

### Install Tauri CLI

Source: https://github.com/ikatson/rqbit/blob/main/DEV-GUIDE.md

Installs the Tauri command-line interface, required for desktop app development.

```bash
cargo install tauri-cli
```

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

### Enable UPnP Server in rqbit

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Starts the rqbit server with UPnP enabled, allowing it to advertise managed torrents to the local network.

```bash
rqbit --enable-upnp-server server start ...
```

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

### Run WebUI Development Server

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Starts the web UI in development mode using Vite, enabling hot reloading. Points to http://localhost:3031.

```bash
# Run webui in dev mode (hot reload vite server). Points to http://localhost:3031.
make webui-dev
```

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

### Run Test Server

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Starts a test server that simulates traffic and points to http://localhost:3030 for the web UI and API. Requires restart if Rust code changes.

```bash
# Run test server that simulates traffic. Points to http://localhost:3030 for the main session's web UI and API.
# If you make changes to Rust this needs to be restarted.
make testserver
```

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

### Build Desktop App

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Installs npm dependencies and compiles TypeScript for the desktop app. Avoids expensive 'cargo tauri build' for development.

```bash
# Desktop app. You cannot test it or see it, so don't bother running expensive "cargo tauri build"
cd desktop && npm install && tsc --noEmit
```

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

### Pause Flow Example

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Describes the state transition when pausing torrents, moving all IN_FLIGHT pieces to QUEUED. This involves marking pieces as broken and storing the ChunkTracker for potential resumption.

```text
IN_FLIGHT → QUEUED (for all in-flight pieces)

1. pause():
   - Calls PieceTracker::into_chunks() which:
     - For each piece in inflight, calls mark_piece_broken_if_not_have(piece)
     - Returns the inner ChunkTracker
   - Stores the ChunkTracker for resume
```

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

### Build Rust Project with WebUI Feature

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Build the project with the 'webui' feature enabled. Requires npm to be installed for frontend asset handling.

```bash
cargo build --release --features webui
```

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

### Run Test Server

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Start a test server that simulates network traffic. It serves the main session's web UI and API on http://localhost:3030. This server must be restarted if Rust code changes.

```bash
make testserver
```

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

### Create Torrent

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Creates a new torrent file from a local folder and starts seeding it.

```APIDOC
## POST /torrents/create

### Description
Creates a new torrent file from a specified local folder and begins seeding it.

### Method
POST

### Endpoint
/torrents/create

### Request Body
- **folder_path** (string) - Required - The path to the local folder to create a torrent from.
```

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

### Start Torrent

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Resumes the download or seeding process for a specific torrent.

```APIDOC
## POST /torrents/{id_or_infohash}/start

### Description
Resumes the download or seeding activity for the specified torrent.

### Method
POST

### Endpoint
/torrents/{id_or_infohash}/start

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Build Rust Project with WebUI Feature

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Builds the Rust project with the 'webui' feature enabled. Requires npm to be installed.

```bash
# Build with webui feature (requires npm installed)
cargo build --release --features webui
```

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

### Import Helper Functions for Formatting

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Imports utility functions for formatting byte sizes, calculating estimated completion times, and getting display names for torrents. These are located in the `helper/` directory.

```typescript
import { formatBytes } from "../helper/formatBytes";
import { getCompletionETA } from "../helper/getCompletionETA";
import { torrentDisplayName } from "../helper/getTorrentDisplayName";
```

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

### Watch Folder for Torrents

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Configures the rqbit server to monitor a specified folder for new .torrent files and automatically start downloading them to a designated path.

```bash
rqbit server start --watch-folder [path] /download/path
```

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

### List Available APIs via HTTP

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Use curl to query the root endpoint of the rqbit HTTP API to get a list of all available APIs and their descriptions. This is useful for understanding the server's capabilities.

```bash
curl -s 'http://127.0.0.1:3030/'

{
  "apis": {
    "GET /": "list all available APIs",
    "GET /dht/stats": "DHT stats",
    "GET /dht/table": "DHT routing table",
    "GET /metrics": "Prometheus metrics",
    "GET /stats": "Global session stats",
    "GET /stream_logs": "Continuously stream logs",
    "GET /torrents": "List torrents",
    "GET /torrents/playlist": "Playlist for supported players",
    "GET /torrents/{id_or_infohash}": "Torrent details",
    "GET /torrents/{id_or_infohash}/haves": "The bitfield of have pieces",
    "GET /torrents/{id_or_infohash}/metadata": "Download the corresponding torrent file",
    "GET /torrents/{id_or_infohash}/peer_stats": "Per peer stats",
    "GET /torrents/{id_or_infohash}/peer_stats/prometheus": "Per peer stats in prometheus format",
    "GET /torrents/{id_or_infohash}/playlist": "Playlist for supported players",
    "GET /torrents/{id_or_infohash}/stats/v1": "Torrent stats",
    "GET /torrents/{id_or_infohash}/stream/{file_idx}": "Stream a file. Accepts Range header to seek.",
    "GET /web/": "Web UI",
    "POST /rust_log": "Set RUST_LOG to this post launch (for debugging)",
    "POST /torrents": "Add a torrent here. magnet: or http:// or a local file.",
    "POST /torrents/create": "Create a torrent and start seeding. Body should be a local folder",
    "POST /torrents/resolve_magnet": "Resolve a magnet to torrent file bytes",
    "POST /torrents/{id_or_infohash}/add_peers": "Add peers (newline-delimited)",
    "POST /torrents/{id_or_infohash}/delete": "Forget about the torrent, remove the files",
    "POST /torrents/{id_or_infohash}/forget": "Forget about the torrent, keep the files",
    "POST /torrents/{id_or_infohash}/pause": "Pause torrent",
    "POST /torrents/{id_or_infohash}/start": "Resume torrent",
    "POST /torrents/{id_or_infohash}/update_only_files": "Change the selection of files to download. You need to POST json of the following form {\"only_files\": [0, 1, 2]}"
  },
  "server": "rqbit",
  "version": "9.0.0-beta.1"
}

```

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

### List Torrent Contents with rqbit

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Prints the contents of a torrent file or magnet link without starting a download. Use the --list flag.

```bash
rqbit --list
```

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

### Checksum Failure Flow Example

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Illustrates the state transition from IN_FLIGHT to QUEUED when a piece's hash verification fails. This involves removing the piece from inflight and marking it as broken.

```text
IN_FLIGHT → QUEUED

1. All chunks received, hash verification fails
2. PieceTracker::take_inflight(piece) → removes from inflight
3. PieceTracker::mark_piece_hash_failed(piece) → calls mark_piece_broken_if_not_have(piece) → sets queue_pieces[p] = true
```

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

### Search Log Files with rg

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Examples of using 'rg' to search log files, with filters for specific content and limiting output. Avoid reading large log files directly.

```bash
# search for peer address
rg "192.168.1.100" /tmp/rqbit-log | head -50      # search for peer address
rg "ERROR" /tmp/rqbit-log | tail -100             # recent errors
rg "abc123" /tmp/rqbit-log | head -20             # search for torrent hash
```

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

### Array Filtering for Virtualization

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/architecture/virtualization.md

When using virtualization, it is mandatory to filter the data array before passing it to the Virtuoso component. This example shows the correct approach compared to a non-virtualized CSS hidden method.

```typescript
// With virtualization - filter first
const filtered = items.filter(item => matchesSearch(item));
<Virtuoso
  totalCount={filtered.length}
  itemContent={(index) => <Item data={filtered[index]} />}
/>

// Without virtualization - CSS hidden (doesn't work with virtualization!)
items.map(item => (
  <Item hidden={!matchesSearch(item)} data={item} />
))
```

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

### Debouncing Search Input

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Example of debouncing search input using `useState` and `useCallback` with `debounce`. This provides instant local feedback while delaying the actual search query update.

```typescript
const [localSearch, setLocalSearch] = useState(searchQuery);
const debouncedSetSearch = useCallback(
  debounce((value: string) => setSearchQuery(value), 150),
  [setSearchQuery]
);
```

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

### Search Log Files with rg

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Filter log files using 'rg' for specific patterns. Always limit output to avoid excessive data. Examples include searching for peer addresses, errors, or torrent hashes.

```bash
rg "192.168.1.100" /tmp/rqbit-log | head -50      # search for peer address
rg "ERROR" /tmp/rqbit-log | tail -100             # recent errors
rg "abc123" /tmp/rqbit-log | head -20             # search for torrent hash
```

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

### Build Web UI

Source: https://github.com/ikatson/rqbit/blob/main/desktop/README.md

Builds the static assets for the rqbit web UI. Execute this command within the webui directory.

```bash
npm run build
```

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

### Build Rust Project (Release)

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Standard command to build the Rust project in release mode.

```bash
# Build (release)
cargo build --release
```

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

### Testing Virtualization Performance

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/architecture/virtualization.md

Use the mock development mode to test with a large dataset and monitor performance metrics in Chrome DevTools. This helps identify potential bottlenecks.

```bash
npm run dev:mock
```

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

### Download Torrents with rqbit

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Initiates a torrent download using a magnet link, .torrent file URL, or local .torrent file. The output directory can be specified with -o.

```bash
rqbit download [-o ~/Downloads] 'magnet:?....' [https?://url/to/.torrent] [/path/to/local/file.torrent]
```

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

### Build Desktop App

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Compile the Tauri desktop application. Note: Testing is not supported, so avoid expensive builds if not necessary.

```bash
cd desktop && npm install && tsc --noEmit
```

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

### Build Desktop App with Tauri

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Builds the desktop application for Linux using Tauri. Pre-built binaries are available for OSX and Windows.

```bash
cargo tauri build
```

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

### Normal Download Flow: QUEUED to COMPLETED

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Illustrates the state transitions from QUEUED to IN_FLIGHT to COMPLETED during a normal download.

```rust
QUEUED → IN_FLIGHT → COMPLETED
```

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

### Format WebUI/Desktop TypeScript

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Format TypeScript files for the web UI and desktop application. Run from the repository root.

```bash
npm run format           # format all
npm run format:check     # check only
```

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

### Development and Build Commands

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Common npm scripts for running the development server, type checking, formatting, and building the web UI. Run `npm run format` from the repo root after modifying TypeScript/TSX files.

```bash
# Dev server (hot reload)
npm run dev  # or: make webui-dev from repo root

# Type check
npx tsc --noEmit

# Format code (run from repo root)
npm run format

# Build
npm run build
```

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

### Configure Socks Proxy for rqbit

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Sets up rqbit to use a SOCKS proxy for its network connections. Supports authentication.

```bash
rqbit --socks-url socks5://[username:password]@host:port ...
```

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

### Configure Basic Auth for HTTP API

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Set the RQBIT_HTTP_BASIC_AUTH_USERPASS environment variable to enable basic authentication for the HTTP API. This requires specifying both username and password.

```bash
RQBIT_HTTP_BASIC_AUTH_USERPASS=username:password rqbit server start ...
```

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

### Format WebUI/Desktop TypeScript

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Commands to format and check TypeScript files for the web UI and desktop application. Run from the repository root.

```bash
# Format webui/desktop TypeScript (run from repo root)
npm run format           # format all
npm run format:check     # check only
```

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

### Configure Bash Shell Completions for rqbit

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Enables bash shell completions for rqbit commands. Add this to your ~/.bashrc file.

```bash
eval "$(rqbit completions bash)"
```

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

### Run Rust Tests

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Commands to run tests for the Rust project. Use '--workspace' to include all members.

```bash
# Run tests
cargo test                    # default members only
cargo test --workspace        # all workspace members
```

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

### Resume Downloading Existing Files

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Resumes downloading a file that already exists. Requires the --overwrite option.

```bash
rqbit --overwrite
```

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

### Add Torrent via Local Torrent File

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Use curl to add a torrent to the rqbit server by uploading a local .torrent file. The file content is sent as binary data in the POST request to the /torrents endpoint.

```bash
curl --data-binary @/tmp/xubuntu-23.04-minimal-amd64.iso.torrent http://127.0.0.1:3030/torrents
```

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

### List Available APIs

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves a list of all available API endpoints and their descriptions.

```APIDOC
## GET /

### Description
Lists all available APIs.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **apis** (object) - An object containing API endpoints and their descriptions.
- **server** (string) - The name of the server.
- **version** (string) - The version of the server.
```

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

### Run Rust Tests

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Execute tests for the project. Use '--workspace' to run tests across all workspace members.

```bash
cargo test                    # default members only
cargo test --workspace        # all workspace members
```

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

### Select Files by Regex

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Filters files within a torrent based on a regular expression applied to their names. Use this to download specific files from a multi-file torrent.

```bash
rqbit -r / --filename-re <regex>
```

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

### Add a torrent

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Adds a new torrent to the server using a magnet link, torrent file URL, or local torrent file.

```APIDOC
## POST /torrents

### Description
Adds a new torrent to the server. Accepts magnet URIs, HTTP(S) URLs to .torrent files, or a local .torrent file.

### Method
POST

### Endpoint
/torrents

### Parameters
#### Query Parameters
- **overwrite** (boolean) - Optional - If true, overwrites existing torrent data.
- **only_files_regex** (string) - Optional - A regular expression to filter filenames for download.
- **output_folder** (string) - Optional - The directory to download files to. Defaults to the server's default download folder.
- **list_only** (boolean) - Optional - If true, only lists files in the torrent without downloading.

#### Request Body
- The body should contain the magnet URI, URL to a .torrent file, or the content of a local .torrent file.

### Request Example
```bash
# Using a magnet link
curl -d 'magnet:?xt=urn:btih:...' http://127.0.0.1:3030/torrents

# Using a torrent file URL
curl -d 'http://example.com/file.torrent' http://127.0.0.1:3030/torrents

# Using a local torrent file
curl --data-binary @/path/to/your/torrent.torrent http://127.0.0.1:3030/torrents
```

### Response
#### Success Response (200)
- Response body typically contains information about the added torrent (details not specified in source).

#### Response Example
(Details not specified in source)
```

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

### Playlist for supported players

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Generates a playlist for supported media players.

```APIDOC
## GET /torrents/playlist

### Description
Generates a playlist for supported players.

### Method
GET

### Endpoint
/torrents/playlist

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- Response body contains a playlist (details not specified in source).

#### Response Example
(Details not specified in source)
```

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

### Add Torrent via Magnet Link

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Use curl to add a torrent to the rqbit server using its magnet link. The magnet URI is sent as data in the POST request to the /torrents endpoint.

```bash
curl -d 'magnet:?...
' http://127.0.0.1:3030/torrents
```

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

### Select Files by Regex

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Uses a regular expression with the -r or --filename-re option to select files by their names for download or processing.

```bash
rqbit -r /--filename-re <regex>
```

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

### Torrent Playlist

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Generates a playlist for supported media players for all torrents.

```APIDOC
## GET /torrents/playlist

### Description
Generates a playlist file for supported media players, listing all torrents.

### Method
GET

### Endpoint
/torrents/playlist
```

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

### Add Torrent via HTTP Torrent File

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Use curl to add a torrent to the rqbit server by providing a URL to a .torrent file. The URL is sent as data in the POST request to the /torrents endpoint.

```bash
curl -d 'http://.../file.torrent' http://127.0.0.1:3030/torrents
```

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

### Web UI

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Accesses the Web User Interface.

```APIDOC
## GET /web/

### Description
Provides access to the Web User Interface for managing torrents.

### Method
GET

### Endpoint
/web/
```

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

### Table View Implementation with react-virtuoso

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/architecture/virtualization.md

Virtualizes the table body for displaying torrents. Each row is rendered as a table, maintaining alignment with a fixed header. No style prop is needed for the rows.

```typescript
// TorrentTable.tsx
const itemContent = useCallback(
  (index: number) => {
    const torrent = filteredTorrents![index];
    return (
      <TorrentTableRow
        torrent={torrent}
        isSelected={selectedTorrentIds.has(torrent.id)}
        onRowClick={handleRowClick}
        onCheckboxChange={toggleSelection}
      />
    );
  },
  [filteredTorrents, selectedTorrentIds, handleRowClick, toggleSelection]
);

return (
  <div className="flex flex-col h-full">
    {/* Fixed header */}
    <table className="w-full table-fixed">
      <thead>...</thead>
    </table>
    {/* Virtualized body */}
    <div className="flex-1 min-h-0">
      <Virtuoso
        totalCount={filteredTorrents?.length ?? 0}
        itemContent={itemContent}
      />
    </div>
  </div>
);
```

```typescript
// TorrentTableRow.tsx - No style prop needed!
return (
  <table className="w-full table-fixed">
    <tbody>
      <tr className="h-[40px]">
        <td className="w-8 align-middle">...</td>
        <td className="w-12 align-middle">...</td>
        {/* ... more cells with explicit widths */}
      </tr>
    </tbody>
  </table>
);
```

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

### Package Dependency for react-virtuoso

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/architecture/virtualization.md

Add react-virtuoso to your project dependencies to enable virtualization. Ensure you are using a compatible version.

```json
{
  "react-virtuoso": "^4.12.5"
}
```

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

### Correct Peer Access Pattern

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Shows the safe way to handle peer interactions by collecting necessary information within a peer lock and processing it outside the lock to prevent deadlocks.

```rust
// GOOD - collect info inside closure, process outside
let steal_info = self.peers.with_live_mut(self.addr, "example", |live| {
    // ... return data needed for on_steal ...
    Some((other_peer, piece))
});
if let Some((from_peer, piece)) = steal_info {
    self.peers.on_steal(from_peer, self.addr, piece);  // Safe - no peer lock held
}
```

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

### Zustand State Management Hooks

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Demonstrates how to read state and call actions from Zustand stores using custom hooks. This is the standard pattern for interacting with global state in the application.

```typescript
// Reading state
const viewMode = useUIStore(state => state.viewMode);
const torrents = useTorrentStore(state => state.torrents);

// Actions
const selectTorrent = useUIStore(state => state.selectTorrent);
selectTorrent(id);
```

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

### Add Torrent

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Adds a new torrent to the server using a magnet link, HTTP URL, or local file.

```APIDOC
## POST /torrents

### Description
Adds a new torrent to the server. Accepts magnet URIs, HTTP URLs pointing to .torrent files, or local .torrent file content.

### Method
POST

### Endpoint
/torrents

### Parameters
#### Query Parameters
- **overwrite** (boolean) - Optional - If true, overwrites an existing torrent with the same infohash.
- **only_files_regex** (string) - Optional - A regular expression to filter which files to download.
- **output_folder** (string) - Optional - The directory where the torrent files should be downloaded. Defaults to the server's default download directory.
- **list_only** (boolean) - Optional - If true, only lists the files in the torrent without downloading.

### Request Body
- **torrent_data** (string or file) - Required - The magnet URI, URL to a .torrent file, or the content of a .torrent file.
```

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

### Torrent Playlist

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Generates a playlist for supported media players for a specific torrent.

```APIDOC
## GET /torrents/{id_or_infohash}/playlist

### Description
Generates a playlist file for supported media players, specific to the given torrent.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/playlist

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Card View Implementation with react-virtuoso

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/architecture/virtualization.md

Renders a list of torrent cards using react-virtuoso. The itemContent function generates the JSX for each card based on the torrent data.

```typescript
import { Virtuoso } from "react-virtuoso";

// Item renderer - receives index, returns JSX
const itemContent = useCallback(
  (index: number) => {
    const torrent = filteredTorrents![index];
    return (
      <div className="pb-2">
        <TorrentCard torrent={torrent} />
      </div>
    );
  },
  [filteredTorrents]
);

return (
  <div className="flex-1 min-h-0">
    <Virtuoso
      totalCount={filteredTorrents.length}
      itemContent={itemContent}
    />
  </div>
);
```

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

### Global session stats

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Retrieves global statistics for the rqbit session.

```APIDOC
## GET /stats

### Description
Provides global session statistics.

### Method
GET

### Endpoint
/stats

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- Response body contains global session statistics (details not specified in source).

#### Response Example
(Details not specified in source)
```

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

### Resume a torrent

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Resumes the download or seeding activity for a specific torrent.

```APIDOC
## POST /torrents/{id_or_infohash}/start

### Description
Resumes the download or seeding process for the specified torrent.

### Method
POST

### Endpoint
/torrents/{id_or_infohash}/start

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.

### Request Example
None

### Response
#### Success Response (200)
- Typically a success message or no content.

#### Response Example
(Details not specified in source)
```

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

### Poll Torrent Stats with Adaptive Interval

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Continuously polls torrent statistics with an adaptive interval that adjusts based on the torrent's state. It polls faster (1s) when the torrent is 'live' and slower (10s) when 'paused'.

```typescript
useEffect(() => {
  return customSetInterval(async () => {
    return API.getTorrentStats(id).then(stats => {
      setStats(stats);
      // Fast poll (1s) when live, slow (10s) when paused
      return stats.state === "live" ? 1000 : 10000;
    });
  }, 0);
}, [forceRefresh]);
```

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

### Piece Stealing Flow: IN_FLIGHT to IN_FLIGHT

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Shows how a piece transitions from being downloaded by one peer to another if the original peer is slow.

```rust
IN_FLIGHT (peer A) → IN_FLIGHT (peer B)
```

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

### Fetch Torrent Details with Retry

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Fetches torrent details once and retries on error using a loop with a specified interval. Useful for initial data loading or when data might be temporarily unavailable.

```typescript
useEffect(() => {
  return loopUntilSuccess(async () => {
    await API.getTorrentDetails(id).then(setDetails);
  }, 1000);
}, [forceRefresh]);
```

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

### Set RUST_LOG

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Sets the RUST_LOG environment variable for debugging purposes after the server has launched.

```APIDOC
## POST /rust_log

### Description
Allows setting the RUST_LOG environment variable for debugging purposes after the server has started.

### Method
POST

### Endpoint
/rust_log

### Request Body
- **log_level** (string) - Required - The desired log level (e.g., "info", "debug", "error").
```

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

### Run Specific Rust Test

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Command to run a specific test within the Rust project, optionally targeting a specific crate.

```bash
# Run a specific test
cargo test <test_name>
cargo test -p librqbit <test_name>   # test in specific crate
```

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

### Prometheus Metrics

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Exposes Prometheus metrics for monitoring.

```APIDOC
## GET /metrics

### Description
Exposes Prometheus metrics for the rqbit server.

### Method
GET

### Endpoint
/metrics
```

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

### DHT Routing Table

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves the DHT routing table.

```APIDOC
## GET /dht/table

### Description
Returns the DHT routing table.

### Method
GET

### Endpoint
/dht/table
```

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

### Increase rqbit Verbosity

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Sets the log level for rqbit to increase verbosity. Accepts 'trace', 'debug', 'info', 'warn', or 'error'.

```bash
rqbit -v <log-level>
```

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

### ChunkTracker Fields

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Tracks piece/chunk download progress. Wrapped by PieceTracker.

```rust
| Field | Type |
|-------|------|
| `have` | `BitVec` |
| `queue_pieces` | `BitVec` |
| `chunk_status` | `BitVec` |
```

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

### PieceTracker Struct

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Tracks piece download state, including chunks and inflight pieces. Lives in TorrentStateLocked.

```rust
pub struct PieceTracker {
    chunks: ChunkTracker,
    inflight: HashMap<ValidPieceIndex, InflightPiece>,
}

pub struct InflightPiece {
    pub peer: PeerHandle,     // Which peer "owns" this piece
    pub started: Instant,     // When download started (for steal threshold)
}
```

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

### Check Rust Compilation Warnings

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Captures all compiler warnings from 'cargo check' to facilitate batch fixing.

```bash
# When fixing compiler warnings, batch all related warnings together and fix them
# in a single pass. Run `cargo check 2>&1` to capture the full list before editing.
cargo check 2>&1
```

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

### Download the corresponding torrent file

Source: https://github.com/ikatson/rqbit/blob/main/README.md

Downloads the torrent file associated with a specific torrent.

```APIDOC
## GET /torrents/{id_or_infohash}/metadata

### Description
Downloads the torrent file (.torrent) for the specified torrent.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/metadata

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.

### Request Example
None

### Response
#### Success Response (200)
- Response body contains the torrent file content.

#### Response Example
(Details not specified in source)
```

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

### API Method Definitions

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Lists common API methods available for interacting with the backend, including their HTTP methods and endpoints. These are typically found in `http-api.ts`.

```typescript
API.listTorrents()           // GET /torrents
API.getTorrentDetails(id)    // GET /torrents/{id}
API.getTorrentStats(id)      // GET /torrents/{id}/stats/v1
API.start(id)                // POST /torrents/{id}/start
API.pause(id)                // POST /torrents/{id}/pause
API.forget(id)               // POST /torrents/{id}/forget (remove from list)
API.delete(id)               // POST /torrents/{id}/delete (remove + delete files)
API.updateOnlyFiles(id, fileIds[])  // POST /torrents/{id}/update_only_files
```

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

### Lint Rust Code

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Check code formatting and style using cargo fmt and cargo clippy.

```bash
cargo fmt --all -- --check
cargo clippy --all-targets
```

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

### Extracting Repetitive CSS Classes

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Demonstrates how to extract repetitive Tailwind CSS class combinations into variables for better maintainability and readability.

```typescript
// BAD - repetitive, hard to maintain
<td className="w-20 px-2 text-right text-secondary whitespace-nowrap align-middle">...</td>
<td className="w-20 px-2 text-right text-secondary whitespace-nowrap align-middle">...</td>
<td className="w-20 px-2 text-right text-secondary whitespace-nowrap align-middle">...</td>

// GOOD - extracted into variable
const numericCell = "w-20 px-2 text-right text-secondary whitespace-nowrap align-middle";
<td className={numericCell}>...</td>
<td className={numericCell}>...</td>
<td className={numericCell}>...</td>
```

```typescript
const cellBase = "px-2 align-middle";
const numericCell = `w-20 ${cellBase} text-right text-secondary whitespace-nowrap`;
```

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

### List Torrents

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves a list of all currently managed torrents.

```APIDOC
## GET /torrents

### Description
Lists all torrents that the server is currently managing.

### Method
GET

### Endpoint
/torrents
```

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

### Add Peers to Torrent

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Manually adds peers to a specific torrent.

```APIDOC
## POST /torrents/{id_or_infohash}/add_peers

### Description
Adds a list of peers to a specific torrent.

### Method
POST

### Endpoint
/torrents/{id_or_infohash}/add_peers

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.

### Request Body
- **peers** (string) - Required - A newline-delimited string of peer addresses (e.g., "ip:port\nip:port").
```

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

### Per Peer Stats (Prometheus)

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves per-peer statistics in Prometheus format.

```APIDOC
## GET /torrents/{id_or_infohash}/peer_stats/prometheus

### Description
Exposes per-peer statistics in Prometheus exposition format for the specified torrent.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/peer_stats/prometheus

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Peer Death Flow: IN_FLIGHT to QUEUED

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/src/torrent_state/live/STATE.md

Details the state transition when a peer dies, requeueing its inflight pieces.

```rust
IN_FLIGHT → QUEUED (for pieces owned by dead peer)
```

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

### Torrent Details

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves detailed information about a specific torrent.

```APIDOC
## GET /torrents/{id_or_infohash}

### Description
Retrieves detailed information about a specific torrent, identified by its ID or infohash.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Lint Rust Code

Source: https://github.com/ikatson/rqbit/blob/main/AGENTS.md

Commands for formatting and linting Rust code using cargo fmt and cargo clippy.

```bash
# Lint
cargo fmt --all -- --check
cargo clippy --all-targets
```

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

### Torrent Stats v1

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves torrent statistics version 1.

```APIDOC
## GET /torrents/{id_or_infohash}/stats/v1

### Description
Provides torrent statistics, version 1.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/stats/v1

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Run Specific Rust Test

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Execute a specific test by name, optionally targeting a particular crate within the workspace.

```bash
cargo test <test_name>
cargo test -p librqbit <test_name>   # test in specific crate
```

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

### Check Rust Compilation

Source: https://github.com/ikatson/rqbit/blob/main/CLAUDE.md

Run 'cargo check' to verify compilation and capture all warnings. This is crucial for identifying and batching fixes for compiler warnings before editing code.

```bash
cargo check 2>&1
```

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

### Check Rust Compilation

Source: https://github.com/ikatson/rqbit/blob/main/GEMINI.md

Captures the full output of 'cargo check' to a file, which is useful for batching and fixing compiler warnings.

```bash
# When fixing compiler warnings, batch all related warnings together and fix them
# in a single pass. Run `cargo check 2>&1` to capture the full list before editing.
```

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

### Trigger Torrent Data Refresh

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Calls the `refreshTorrents` action from the `torrentStore` to manually trigger a refresh of all torrent data. This is useful for ensuring the UI is up-to-date.

```typescript
const refreshTorrents = useTorrentStore(state => state.refreshTorrents);
refreshTorrents();
```

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

### Display and Set Closeable Error

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Shows how to display an error message to the user and store it in the `errorStore`. The error can be made closeable by the user.

```typescript
const setCloseableError = useErrorStore(state => state.setCloseableError);
setCloseableError({ text: "Error message", details: error });
```

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

### Global Session Stats

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves global statistics for the current session.

```APIDOC
## GET /stats

### Description
Provides global session statistics.

### Method
GET

### Endpoint
/stats
```

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

### Download Torrent Metadata

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Downloads the torrent file metadata for a specific torrent.

```APIDOC
## GET /torrents/{id_or_infohash}/metadata

### Description
Downloads the torrent file (.torrent) associated with the specified torrent ID or infohash.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/metadata

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Stream Logs

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Continuously streams server logs.

```APIDOC
## GET /stream_logs

### Description
Continuously streams server logs in real-time.

### Method
GET

### Endpoint
/stream_logs
```

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

### Torrent Have Pieces

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Retrieves the bitfield representing the pieces a torrent has.

```APIDOC
## GET /torrents/{id_or_infohash}/haves

### Description
Returns the bitfield representing the pieces of the torrent that have been downloaded.

### Method
GET

### Endpoint
/torrents/{id_or_infohash}/haves

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```

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

### Display Loading Spinner

Source: https://github.com/ikatson/rqbit/blob/main/crates/librqbit/webui/CLAUDE.md

Conditionally renders a loading spinner component when data is not yet available. This is a common pattern for handling asynchronous data fetching.

```typescript
if (!data) return <Spinner />; 
```

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

### Update Torrent Files Selection

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Updates the selection of files to download for a torrent.

```APIDOC
## POST /torrents/{id_or_infohash}/update_only_files

### Description
Allows changing the selection of files to download for a torrent. This is useful for selective downloading.

### Method
POST

### Endpoint
/torrents/{id_or_infohash}/update_only_files

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.

### Request Body
- **only_files** (array of integers) - Required - A JSON array containing the indices of the files to download.
```

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

### Resolve Magnet URI

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Resolves a magnet URI to its corresponding torrent file bytes.

```APIDOC
## POST /torrents/resolve_magnet

### Description
Resolves a given magnet URI and returns the content of the corresponding .torrent file.

### Method
POST

### Endpoint
/torrents/resolve_magnet

### Request Body
- **magnet_uri** (string) - Required - The magnet URI to resolve.
```

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

### Pause Torrent

Source: https://github.com/ikatson/rqbit/blob/main/crates/rqbit/README.md

Pauses the download or seeding process for a specific torrent.

```APIDOC
## POST /torrents/{id_or_infohash}/pause

### Description
Pauses the download or seeding activity for the specified torrent.

### Method
POST

### Endpoint
/torrents/{id_or_infohash}/pause

### Parameters
#### Path Parameters
- **id_or_infohash** (string) - Required - The ID or infohash of the torrent.
```