Transmission 4.1.4 常用 CLI 命令与工具详解

目标：以 transmission-remote 为核心，配合 transmission-create / transmission-show / transmission-edit / transmission-daemon，覆盖 Transmission 服务器形态的日常命令行管理：任务增删查改、限速、校验、做种策略、种子制作与改写。已在 Ubuntu 24.04 LTS（x86_64）+ Transmission 4.1.4（daemon + RPC 9091）环境实测通过（2026-11-01），全部回显为实测原文。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64）
软件版本：Transmission 4.1.4（transmission-remote --version → transmission-remote 4.1.4 (a6d907d9ea)）
运行形态：transmission-daemon 常驻，RPC 服务 127.0.0.1:9091
认证状态：RPC 已开启认证，示例账号 admin / q1w2e3r4（未开认证时去掉 -n 参数即可）
示例数据：下载目录 /opt/downloads/complete/ 下有一个 8.39 MB 的测试文件 ubuntu-24.04-desktop-amd64.iso，对应任务 Hash 2514964bc612ced78058b1664c0c9e2d5adf6d37
工具集：transmission-daemon、transmission-remote、transmission-create、transmission-show、transmission-edit（随 transmission-cli/daemon 包安装）

二、工具概览

Transmission 的命令行生态是「一个常驻进程 + 四个客户端/工具」，分工如下：

工具	角色	典型场景
transmission-daemon	常驻守护进程本体	服务器后台运行，暴露 RPC 与 Web UI
transmission-remote	RPC 控制客户端	日常管理：加任务、限速、校验、查状态（本文主体）
transmission-create	种子制作工具	把文件/目录打成 .torrent
transmission-show	种子信息查看	读取 .torrent 元数据（不连网）
transmission-edit	种子元数据修改	增删改 tracker、改 source

连接模型：所有管理操作都是「客户端 → daemon 的 RPC 接口」，daemon 可与本机 remote 同机，也可被任意网络的 remote/App 控制（端口与认证对齐即可）。因此 remote 的第一个参数永远是 daemon 地址，本机默认 127.0.0.1:9091。

三、前置条件

daemon 已启动且 RPC 可达（transmission-remote 127.0.0.1:9091 -si 有 VERSION 输出）；
已知 RPC 凭据（若 rpc-authentication-required=true）；未开认证可直接执行不带 -n 的命令；
本机装有 transmission-cli/daemon 工具包（which transmission-remote 可找到）。

验证连通（未开认证的空会话）：

transmission-remote 127.0.0.1:9091 -l

实测回显：

    ID    Done       Have  ETA              Up      Down  Ratio  Status       Name
Sum:                 None                  0.0       0.0

四、transmission-remote 详解

完整帮助 transmission-remote --help 共 302 行（4.1.4），覆盖全部管理能力。本章按使用场景分组讲核心参数，全部命令与回显均为实测。书写约定：remote 代指 transmission-remote 127.0.0.1:9091；开启认证时统一写成 remote -n admin:q1w2e3r4。

4.1 连接指定与认证

remote 支持四种连接写法（摘自 --help 原文）：

Usage: transmission-remote [host] [options]
       transmission-remote [port] [options]
       transmission-remote [host:port] [options]
       transmission-remote [http(s?)://host:port/transmission/] [options]

认证三种方式（实测）：

# 方式一：-n 明文用户名密码
transmission-remote 127.0.0.1:9091 -n admin:q1w2e3r4 -l

# 方式二：TR_AUTH 环境变量 + -ne（避免凭据进 shell history）
TR_AUTH=admin:q1w2e3r4 transmission-remote 127.0.0.1:9091 -ne -l

# 方式三：-N 指定 netrc 文件
transmission-remote 127.0.0.1:9091 -N ~/.netrc -l

方式二实测回显：

    ID    Done       Have  ETA              Up      Down  Ratio  Status       Name
     1    100%    8.39 MB  Done            0.0       0.0   0.00  Idle         ubuntu-24.04-desktop-amd64.iso
Sum:              8.39 MB                  0.0       0.0

认证开启后不带凭据的实测报错（也是密码错误时的报错）：

Unexpected response: <h1>401: Unauthorized</h1>

退出码为 1。日常建议：交互环境用 TR_AUTH，脚本里用 netrc（chmod 600）。

4.2 任务列表与筛选

remote -l

实测回显（列含义：ID/完成度/已持有量/预计剩余时间/上传速度/下载速度/分享率/状态/任务名，Sum 行为合计）：

    ID    Done       Have  ETA              Up      Down  Ratio  Status       Name
     1    100%    8.39 MB  Done            0.0       0.0   0.00  Idle         ubuntu-24.04-desktop-amd64.iso
Sum:              8.39 MB                  0.0       0.0

Status 取值含义：Downloading（下载中）、Seeding（做种中）、Idle（已完成为做种或暂停后闲置）、Stopped（手动暂停/排队中）、Verifying（校验中）。

条件筛选（实测按标签过滤）：

remote -l -F "label=demo"

实测回显：

    ID    Done       Have  ETA              Up      Down  Ratio  Status       Name
     1    100%    8.39 MB  Done            0.0       0.0   0.00  Idle         ubuntu-24.04-desktop-amd64.iso
Sum:              8.39 MB                  0.0       0.0

-F 支持的判据还包括 id/name/status 等（如 -F "status=Stopped"）。取纯 ID 列表供脚本消费用 -ids。

4.3 添加任务（-a）

remote -a /opt/torrents/demo.torrent           # 本地 .torrent 文件
remote -a "magnet:?xt=urn:btih:2514964bc612ced78058b1664c0c9e2d5adf6d37"   # 磁力链接
remote -a http://example.com/demo.torrent      # URL

实测回显（成功）：

127.0.0.1:9091/transmission/rpc/ returned a successful response

添加后 -l 立即可见（本地已有数据时校验后直达 100%，实测）：

    ID    Done       Have  ETA              Up      Down  Ratio  Status       Name
     2    100%    8.39 MB  Done            0.0       0.0   0.00  Idle         ubuntu-24.04-desktop-amd64.iso
Sum:              8.39 MB                  0.0       0.0

实用搭配参数：

-w <目录>：与 -a 同用时指定该任务的下载目录（不加则落 download-dir）；
--start-paused / --no-start-paused：本次添加的任务暂停入列/立即开始（会话级开关）；
--trash-torrent：添加成功后删除原 .torrent 文件。

💡 技术拓展：添加任务的另一条路是「监视目录」——daemon 的 watch-dir 开启时，把 .torrent 丢进监视目录即自动导入并改名为 .torrent.added。CLI 的 -a 与 watch 目录的本质都是走 torrent-add RPC；区别是 -a 即时可控（回显成功/失败），watch 适合自动投递流水线。

4.4 任务详情查看（-i / -f / -it / -ip / -si / -st）

单任务全景信息（-t <id> -i，输出较长，实测原文照录）：

remote -t 1 -i

实测回显：

NAME
  Id: 1
  Name: ubuntu-24.04-desktop-amd64.iso
  Hash: 2514964bc612ced78058b1664c0c9e2d5adf6d37
  Magnet: magnet:?xt=urn:btih:2514964bc612ced78058b1664c0c9e2d5adf6d37&dn=ubuntu-24.04-desktop-amd64.iso
  Labels: 

TRANSFER
  State: Idle
  Location: /opt/downloads/complete
  Sequential Download: No
  Sequential Download from piece: 0
  Percent Done: 100%
  ETA: 0 seconds (0 seconds)
  Download Speed: 0 B/s
  Upload Speed: 0 B/s
  Have: 8.39 MB (8.39 MB verified)
  Availability: 100%
  Total size: 8.39 MB (8.39 MB wanted)
  Downloaded: None
  Uploaded: None
  Ratio: 0.00
  Peers: connected to 0, uploading to 0, downloading from 0

HISTORY
  Date added:       Sun Nov 01 14:45:32 2026
  Date finished:    Sun Nov 01 14:45:32 2026
  Date started:     Sun Nov 01 14:45:32 2026
  Seeding Time:     48 seconds (48 seconds)

ORIGINS
  Date created: Sun Nov 01 14:45:32 2026
  Public torrent: Yes
  Comment: demo torrent for cli test
  Creator: Transmission/4.1.4 (a6d907d9ea)
  Piece Count: 1
  Piece Size: 1 GiB

LIMITS & BANDWIDTH
  Download Limit: Unlimited
  Upload Limit: Unlimited
  Ratio Limit: Default
  Idle Limit: Default
  Honors Session Limits: Yes
  Peer limit: 50
  Bandwidth Priority: Normal

（Magnet 行可直接复制给他人做磁力分享；HISTORY 是时间线；LIMITS & BANDWIDTH 是该任务的独立限额，Default 表示跟随会话全局值。）

文件级信息（-t 1 -f，实测）：

ubuntu-24.04-desktop-amd64.iso (1 files):
  #   Done Priority Get      Size  Name
  0:  100% Normal   Yes 8.39 MB    ubuntu-24.04-desktop-amd64.iso

多文件任务里常用它配合优先级参数：-ph <files> 高优先、-pn 普通、-pl 低优先、-g <files> 标记下载、-G <files> 标记跳过。

会话级信息（-si，实测回显节选）：

VERSION
  Daemon version: 4.1.4 (a6d907d9ea)
  RPC version: 19
  RPC minimum version: 14

CONFIG
  Configuration directory: /etc/transmission-daemon
  Download directory: /opt/downloads/complete
  Listen port: 51413
  Port forwarding enabled: Yes
  µTP enabled: No
  Distributed hash table enabled: Yes
  Local peer discovery enabled: No
  Peer exchange allowed: Yes
  Encryption: preferred
  Maximum memory cache size: 4 MiB
  Sequential download: No

LIMITS
  Peer limit: 200
  Default seed ratio limit: Unlimited
  Default idle seeding time limit: Unlimited
  Upload speed limit: Unlimited (Disabled limit: 200 kB/s; Disabled turtle limit: 50 kB/s)
  Download speed limit: Unlimited (Disabled limit: 500 kB/s; Disabled turtle limit: 50 kB/s)

MISC
  Autostart added torrents: Yes
  Delete automatically added torrents: No

历史流量统计（-st，实测）：

CURRENT SESSION
  Uploaded:   None
  Downloaded: None
  Ratio:      None
  Duration:   1 hour, 54 minutes (6893 seconds)

TOTAL
  Started 1 times
  Uploaded:   None
  Downloaded: None
  Ratio:      None
  Duration:   1 hour, 54 minutes (6893 seconds)

任务关联 tracker 列表 -t 1 -it、peer 列表 -t 1 -ip（公网任务才有内容）、分片状态 -t 1 -ic。JSON 输出可加 -j 供脚本解析。

4.5 任务控制（-s / -S / -v / -r / -rad / --find / -L）

启停与校验（实测）：

remote -t 1 -S          # 暂停
remote -t 1 -s          # 恢复
remote -t 1 -v          # 校验本地数据完整性

暂停后列表状态变为 Stopped，恢复后回到 Idle（实测节选）：

     2    100%    8.39 MB  Done            0.0       0.0   0.00  Stopped      ubuntu-24.04-desktop-amd64.iso
     2    100%    8.39 MB  Done            0.0       0.0   0.00  Idle         ubuntu-24.04-desktop-amd64.iso

校验命令的回显是通知确认，实际校验在后台进行（-l 里短暂出现 Verifying 状态）：

127.0.0.1:9091/transmission/rpc/ acknowledged notification

删除任务（实测）：

remote -t 2 -r          # 仅移除任务，保留已下载数据
remote -t 2 -rad        # 移除任务并删除本地数据（危险，确认后再敲）

实测回显：

127.0.0.1:9091/transmission/rpc/ acknowledged notification

移动与定位：

--find <路径>：数据文件被手工挪动后，告诉 daemon 新位置（避免重新校验）；
--rename <新名> [--path <旧路径>]：在线重命名任务根目录或内部文件。

标签管理（实测）：

remote -t 1 -L demo,linux      # 打标签
remote -t 1 -i | grep -i label # 核对

实测回显：

  Labels: demo, linux

4.6 限速管理（-d / -u / -D / -U 与 alt-speed 组）

会话全局限速（实测）：

remote -d 500 -u 200        # 下载 500 kB/s、上传 200 kB/s，并同时启用
remote -si | sed -n '/LIMITS/,/MISC/p'
remote -D -U                # 解除两项限制

生效回显（实测）：

  Upload speed limit: 200 kB/s (Enabled limit: 200 kB/s; Disabled turtle limit: 50 kB/s)
  Download speed limit: 500 kB/s (Enabled limit: 500 kB/s; Disabled turtle limit: 50 kB/s)

「乌龟模式」双档切换组：

remote -as                # 切到乌龟档（限速档）
remote -AS                # 切回普通档
remote -asd 100           # 设乌龟档下载限速
remote -asu 50            # 设乌龟档上传限速
remote -asc               # 启用按时段自动切换
remote -ASC               # 关闭时段自动切换
remote --alt-speed-time-begin 540 --alt-speed-time-end 1020 --alt-speed-days 1-7

不带 -t 参数时以上限速作用于会话全局；带 -t <id> 时作用于单任务（配合 -hl/-HL 控制该任务是否遵守会话限速）。

4.7 做种策略（-sr / -gsr / -isl 组）

remote -gsr 2.0           # 全局分享率 2.0（单任务覆盖用 -sr）
remote -SR                # 取消分享率限制
remote -t 1 -sr 3.0       # 单任务分享率 3.0
remote -gisl 120          # 全局空闲做种上限 120 分钟
remote -ISL               # 取消空闲做种限制

达到上限的任务自动停止做种（状态转 Stopped/Idle），配合队列参数可实现「下完做到 2.0 就让位」的自动化。

4.8 协议与端口（-pt / -o / -x / -y / -p / -m）

remote -pt                # 端口连通性测试
remote -p 51413           # 设 peer 传入端口
remote -o / -O            # 开/关 DHT
remote -x / -X            # 开/关 PEX
remote -y / -Y            # 开/关 LPD
remote -m / -M            # 开/关 UPnP/NAT-PMP 端口映射
remote -er / -ep / -et    # peer 加密：必需/偏好/容忍

-pt 实测回显（服务器位于内网 NAT 后、未做公网映射时的真实结果）：

Port is open: No

公网可达的 seedbox 上同命令应显示 Port is open: Yes。内网环境此结果不代表故障，判断依据是实际下载速度与 peer 连接数。

4.9 会话级杂项与远程关停

remote -e 32              # 调整内存写缓存（MiB）
remote -c /opt/downloads/incomplete   # 改未完成暂存目录
remote -C                 # 取消暂存目录（未完成与完成同目录）
remote --exit             # 让 daemon 优雅退出（systemd 环境请用 systemctl stop 代替）

五、transmission-create 详解

把本地文件/目录制作为 .torrent。帮助原文：

Usage: transmission-create [options] <file|directory>

Options:
 -h --help                Display this help page and exit
 -p --private             Allow this torrent to only be used with the specified
                          tracker(s)
 -r --source    <source>  Set the source for private trackers
 -o --outfile   <file>    Save the generated .torrent to this filename
 -s --piecesize <KiB>     Set the piece size in KiB, overriding the preferred
                          default
 -c --comment   <comment> Add a comment
 -t --tracker   <url>     Add a tracker's announce URL
 -w --webseed   <url>     Add a webseed URL
    --anonymize           Omit "Creation date" and "Created by" info
 -V --version             Show version number and exit

制作带 tracker 的私有种子（实测）：

transmission-create -o /opt/torrents/demo-private.torrent \
  -t "http://tracker.example.com:6969/announce" \
  -p -r "my-source" -c "private demo" \
  /opt/downloads/complete/ubuntu-24.04-desktop-amd64.iso

实测回显：

Creating torrent "/opt/torrents/demo-private.torrent"
1 file, 8.39 MB
512 pieces, 16 KiB each
 done!

不指定 tracker 时的实测回显（有 WARNING 但照常生成，适合本地场景）：

WARNING: no trackers specified
Creating torrent "/opt/torrents/demo.torrent"
1 file, 8.39 MB
1 piece, 1 GiB
 done!

参数要点：-p 私有种子（禁用 DHT/PEX/LPD，内部分发专用，需配合 -t 指定 tracker 才有意义）；-s 分片大小 KiB（不指定按总大小自动选，实测 8.39MB 自动选 16 KiB/512 片）；--anonymize 去掉创建时间与工具签名。

六、transmission-show 详解

离线读取 .torrent 元数据，不连任何服务器：

transmission-show /opt/torrents/demo.torrent

实测回显（全文）：

Name: ubuntu-24.04-desktop-amd64.iso
File: /opt/torrents/demo.torrent

GENERAL

  Name: ubuntu-24.04-desktop-amd64.iso
  Hash v1: 2514964bc612ced78058b1664c0c9e2d5adf6d37
  Created by: Transmission/4.1.4 (a6d907d9ea)
  Created on: Sun Nov 01 14:45:32 2026

  Comment: demo torrent for cli test
  Piece Count: 1
  Piece Size: 1 GiB
  Total Size: 8.39 MB
  Privacy: Public torrent

TRACKERS

FILES

  ubuntu-24.04-desktop-amd64.iso (8.39 MB)

带 tracker 的种子会在 TRACKERS 段列出 Tier 与 announce 地址；Privacy: Private torrent 即私有标记。加磁力链接做参数（transmission-show -m <magnet>）可把磁力转 .torrent 文件。

七、transmission-edit 详解

直接改写 .torrent 文件的 announce 信息（4.1.4 帮助原文）：

Usage: transmission-edit [options] torrent-file(s)

Options:
 -h --help                Display this help page and exit
 -a --add     <url>       Add a tracker's announce URL
 -d --delete  <url>       Delete a tracker's announce URL
 -r --replace <old> <new> Search and replace a substring in the announce URLs
 -s --source  <source>    Set the source
 -V --version             Show version number and exit

三连实测（加 → 换 → 删）：

transmission-edit -a "http://tracker.example.com:6969/announce" /opt/torrents/demo.torrent

/opt/torrents/demo.torrent
	Added 'http://tracker.example.com:6969/announce' in 'announce'
Changed 1 files

transmission-edit -r "tracker.example.com" "tracker.newdomain.org" /opt/torrents/demo.torrent

/opt/torrents/demo.torrent
	Replaced in 'announce': 'http://tracker.example.com:6969/announce' --> 'http://tracker.newdomain.org:6969/announce'
Changed 1 files

transmission-edit -d "http://tracker.newdomain.org:6969/announce" /opt/torrents/demo.torrent

/opt/torrents/demo.torrent
	Removed 'http://tracker.newdomain.org:6969/announce' from 'announce'
Changed 1 files

每次修改后用 transmission-show 的 TRACKERS 段核对结果。注意：旧版本支持改 Comment 的 -c 选项在 4.x 已不存在，实测传入 -c 直接报错：

ERROR: Must specify -a, -d, -r or -s

八、transmission-daemon 启动参数

daemon 的运行时覆盖参数（help 节选，实测 transmission-daemon --help）：

Usage: transmission-daemon [options]

Options:
 -h   --help                                 Display this help page and exit
 -a   --allowed                <list>        Allowed IP addresses. (Default:
                                             127.0.0.1,::1)
 -b   --blocklist                            Enable peer blocklists
 -B   --no-blocklist                         Disable peer blocklists
 -c   --watch-dir              <directory>   Where to watch for new torrent
                                             files
 -C   --no-watch-dir                         Disable the watch-dir
      --incomplete-dir         <directory>   Where to store new torrents until
                                             they're complete
      --no-incomplete-dir                    Don't store incomplete torrents in
                                             a different location
 -d   --dump-settings                        Dump the settings and exit
      --default-trackers       <list>        Trackers for public torrents to
                                             use automatically
 -e   --logfile                <filename>    Dump the log messages to this
                                             filename
 -f   --foreground                           Run in the foreground instead of
                                             daemonizing
 -g   --config-dir             <path>        Where to look for configuration
                                             files
 -p   --port                   <port>        RPC port (Default: 9091)
 -t   --auth                                 Require authentication
 -T   --no-auth                              Don't require authentication
 -u   --username               <username>    Set username for authentication
 -v   --password               <password>    Set password for authentication
 -V   --version                              Show version number and exit
      --log-level              <level>       Must be 'critical', 'error',
                                             'warn', 'info', 'debug', or
                                             'trace'.

实用组合：

-d（dump-settings）：把当前会话完整配置打到 stdout 退出，是核对配置的利器；
-f（前台）：systemd 或进程管理器托管环境的标准运行方式；
-g <目录>：多实例并行时各用独立配置目录（配置、resume、状态文件全隔离）；
-t -u <用户> -v <密码>：命令行直接注入认证（首启初始化场景）。

九、注意事项

409 Session-Id 机制：直接用 curl/脚本对接 RPC 时，首个 POST 会返回 409 Conflict 并在响应头 X-Transmission-Session-Id 给出会话令牌，后续请求必须回带该头（防 CSRF 设计）。transmission-remote 已自动处理，无需关心；实测 409 响应体节选：
```
<h1>409: Conflict</h1><p>Your request had an invalid session_id header.</p>
```
任务 ID 不跨重启：-l 列表里的 ID 是会话内序号，daemon 重启后同一任务 ID 会变（实测：重启前 ID 2，重启后同一任务变 ID 1）。脚本处理要用 -ids 实时获取，不要缓存 ID。
-rad 不可逆：移除并删除本地数据没有二次确认，多文件任务先 -t <id> -f 核对再执行。
--rename 的适用范围：4.1.4 实测对单文件任务直接 rename 根名返回 Error: Invalid argument，该参数主要面向目录型任务的内部路径改名；改名需求优先考虑任务级删除重建或直接在文件系统层操作后 --find 重新定位。
限速单位：全部是 kB/s；-d/-u 设值即启用，解除用 -D/-U，不要用设 0 当「解除」。

十、常见问题

Q1：执行命令报 Unexpected response: <h1>401: Unauthorized</h1>？

daemon 开了认证而命令没带凭据（或密码错）。-n admin:q1w2e3r4、TR_AUTH=admin:q1w2e3r4 配 -ne、-N ~/.netrc 三选一（见 4.1）。

Q2：-a 添加磁力链接后 -l 里任务名是乱码或 metadata？

磁力链接需要先向 peer 网络获取元数据，任务短暂显示为元数据获取状态是正常现象；DHT/PEX 关闭且无 tracker 的磁力会一直卡在获取阶段，此时检查协议开关（4.8）或改用 .torrent 文件。

Q3：--blocklist-update 报 Couldn't fetch blocklist: Not Found (404)？

settings.json 的 blocklist-url 还是默认占位地址 http://www.example.com/blocklist（实测即 404）。改成真实黑名单列表地址后再更新。

Q4：远程管理服务器上的 daemon 怎么写连接参数？

transmission-remote <服务器IP>:9091 -n admin:q1w2e3r4 -l。前提：daemon 的 rpc-bind-address 未限定 127.0.0.1、防火墙放行 RPC 端口、认证已开启（公网暴露 RPC 必须认证，生产建议加 IP 白名单，见配置篇 RPC 组）。

Q5：怎么把 -l 结果接给 shell 脚本？

-ids 取 ID 列表、-j 取 JSON 输出（配 jq 解析）、-F 按条件过滤，三者组合可覆盖巡检/批量操作场景。注意 ID 跨重启会变（见第九章第 2 条）。

十一、参考链接

《Transmission 4.1.4 介绍与选型指南》：定位与同类客户端选型对比
《Transmission 4.1.4 Docker Compose 部署指南》：容器形态部署与三目录挂载
《Transmission 4.1.4 配置参数详解》：settings.json 全参数与生效机制
transmission-remote 手册页：https://man.archlinux.org/man/transmission-remote.1
GitHub 仓库：https://github.com/transmission/transmission