MoviePilot/docs/cli.md

MoviePilot CLI

moviepilot 是 MoviePilot 本地源码模式的一体化入口，负责本地安装、初始化、更新，以及前后端服务管理。

一键安装

curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v2/scripts/bootstrap-local.sh | bash

脚本会自动：

• 检测操作系统
• 自动检查并尽量安装 git、curl、Python 3.11+
• 克隆 MoviePilot
• 安装后端依赖
• 下载 MoviePilot-Frontend 最新 release 的 dist.zip
• 下载 MoviePilot-Resources 主分支资源
• 将 resources.v2/* 同步到后端 app/helper
• 下载本地 Node 运行时并安装前端运行依赖
• 执行初始化向导
• 创建全局 moviepilot 命令
• 默认启动前后端服务

说明：

• 如果系统里已经有可用的 Python 3.11+，脚本会优先直接复用本地解释器
• 如果系统里没有可用的 Python 3.11+，脚本会再尝试自动补齐运行环境
• Linux 下安装系统依赖时通常需要 sudo
• 复用已有仓库时，脚本现在只会因为已跟踪源码改动而阻止自动更新，不会再被 .DS_Store 之类未跟踪文件卡住

如果安装完成后当前终端仍提示找不到 moviepilot：

• 重新打开终端
• 如果脚本提示使用了 ~/.local/bin，执行 source ~/.zshrc 或 source ~/.bashrc

配置目录

本地 CLI 默认将配置目录放在程序目录外，避免直接删除程序目录时把配置一并删掉。

• macOS：~/Library/Application Support/MoviePilot
• Linux：${XDG_CONFIG_HOME:-~/.config}/moviepilot

如果在交互式终端中执行一键安装脚本，或直接执行 moviepilot setup / moviepilot init 且未传入 --config-dir，程序会先询问配置目录，并把上面的默认路径作为默认值展示出来。

可以在安装或初始化时手动指定：

moviepilot setup --config-dir /path/to/moviepilot-config
moviepilot init --config-dir /path/to/moviepilot-config

查看当前实际配置目录：

moviepilot config path

目录说明

• 后端代码：仓库根目录
• 外置配置目录：moviepilot config path 输出的 Config Dir
• 前端静态文件：public/
• 前端本地 Node 运行时：.runtime/node/
• 后端日志：<Config Dir>/logs/moviepilot.log
• 后端启动日志：<Config Dir>/logs/moviepilot.stdout.log 该文件同样受 LOG_MAX_FILE_SIZE 与 LOG_BACKUP_COUNT 控制
• 前端启动日志：<Config Dir>/logs/moviepilot.frontend.stdout.log

帮助与发现

根帮助：

moviepilot --help
moviepilot help
moviepilot commands

分级帮助：

moviepilot help install
moviepilot help init
moviepilot help setup
moviepilot help uninstall
moviepilot help update
moviepilot help agent
moviepilot help config
moviepilot help config set
moviepilot help tool
moviepilot help scheduler

配置项清单与说明：

moviepilot config keys
moviepilot config keys API
moviepilot config describe API_TOKEN

动态工具清单与参数说明：

moviepilot tool list
moviepilot tool show <tool_name>

完整命令清单

moviepilot install deps
moviepilot install frontend
moviepilot install resources
moviepilot init
moviepilot setup
moviepilot uninstall
moviepilot update backend
moviepilot update frontend
moviepilot update all
moviepilot startup enable
moviepilot startup disable
moviepilot startup status
moviepilot agent
moviepilot start
moviepilot stop
moviepilot restart
moviepilot status
moviepilot logs
moviepilot version
moviepilot config path
moviepilot config list
moviepilot config get
moviepilot config set
moviepilot config keys
moviepilot config describe
moviepilot tool list
moviepilot tool show
moviepilot tool run
moviepilot scheduler list
moviepilot scheduler run
moviepilot help
moviepilot commands

安装命令

安装后端依赖：

moviepilot install deps
moviepilot install deps --python python3.11
moviepilot install deps --venv /path/to/venv
moviepilot install deps --recreate
moviepilot install deps --config-dir /path/to/moviepilot-config

说明：

• 默认会自动选择本地已安装的 Python 3.11+ 解释器

安装前端 release：

moviepilot install frontend
moviepilot install frontend --version latest
moviepilot install frontend --version v2.9.31
moviepilot install frontend --node-version 20.12.1
moviepilot install frontend --config-dir /path/to/moviepilot-config

说明：

• 默认下载 MoviePilot-Frontend 最新 release 的 dist.zip
• 会自动安装本地 Node 运行时
• 会自动安装 service.js 所需的运行依赖

安装资源文件：

moviepilot install resources
moviepilot install resources --resources-repo /path/to/MoviePilot-Resources
moviepilot install resources --resource-dir /path/to/resources.v2
moviepilot install resources --config-dir /path/to/moviepilot-config

说明：

• 默认直接从 GitHub 下载 MoviePilot-Resources 主分支压缩包
• 会将 resources.v2/* 整体复制到 app/helper
• 这一步和 Docker 构建流程保持一致

初始化命令

初始化本地配置：

moviepilot init
moviepilot init --wizard
moviepilot init --skip-resources
moviepilot init --force-token
moviepilot init --superuser admin --superuser-password 'ChangeMe123!'
moviepilot init --config-dir /path/to/moviepilot-config

一体化安装：

moviepilot setup
moviepilot setup --wizard
moviepilot setup --frontend-version latest
moviepilot setup --node-version 20.12.1
moviepilot setup --skip-resources
moviepilot setup --recreate
moviepilot setup --superuser admin --superuser-password 'ChangeMe123!'
moviepilot setup --config-dir /path/to/moviepilot-config

moviepilot setup 会串行执行：

1. 安装后端依赖
2. 下载并安装前端 release
3. 下载并同步资源文件
4. 初始化本地配置

--wizard 会进入交互式初始化向导，支持配置：

• API_TOKEN
• 超级管理员用户名与密码
• 数据库类型 默认 SQLite 可切换为 PostgreSQL，并填写主机、端口、数据库名、用户名、密码
• 默认下载目录与媒体库目录
• AI Agent 可按需启用，并配置 LLM_PROVIDER、LLM_MODEL、LLM_API_KEY、LLM_BASE_URL
• 用户站点认证 可按需选择认证站点，并按站点要求填写用户名、UID、Passkey 等参数
• 开机自启 可按需启用，MoviePilot 会根据当前操作系统注册登录自启动
• 下载器
• 媒体服务器
• 消息通知渠道

如果希望在自动化安装时直接预设超级管理员，也可以在一键安装脚本中透传：

curl -fsSL https://raw.githubusercontent.com/jxxghp/MoviePilot/v2/scripts/bootstrap-local.sh | \
  bash -s -- --superuser admin --superuser-password 'ChangeMe123!'

说明：

• --superuser-password 更适合自动化场景，命令可能会出现在 shell 历史中
• 交互式 --wizard 会在初始化过程中提示输入超级管理员用户名和密码

开机自启命令

管理当前本地安装的开机自启：

moviepilot startup status
moviepilot startup enable
moviepilot startup disable
moviepilot startup enable --venv /path/to/venv
moviepilot startup enable --config-dir /path/to/moviepilot-config

说明：

• macOS 使用 LaunchAgent
• Linux 优先使用 systemd --user，当前环境不可用时自动回退到 XDG autostart
• Windows 使用当前用户的 Startup 启动目录
• 注册的启动项会调用本地 CLI 的统一启动入口，因此会同时拉起后端与前端

卸载命令

卸载本地安装产物：

moviepilot uninstall
moviepilot uninstall --venv /path/to/venv
moviepilot uninstall --config-dir /path/to/moviepilot-config

说明：

• 卸载时会先停止当前 CLI 管理的前后端服务
• 会删除本地虚拟环境、前端运行时、本地 Node 运行时、全局 moviepilot 软链接，以及同步到 app/helper 的资源文件
• 如果之前注册过开机自启，卸载时也会一并取消
• 会询问是否同时删除配置目录，默认不删除
• 如果当前使用的是仓库内 legacy config/ 目录，确认删除后其中的 category.yaml 等配置文件也会一起删除
• 整个卸载流程包含两次确认
• 源码目录会保留，如需彻底移除仓库请在确认后手动删除项目目录

更新命令

更新后端：

moviepilot update backend
moviepilot update backend --ref latest
moviepilot update backend --ref v2
moviepilot update backend --ref v2.9.31

更新前端：

moviepilot update frontend
moviepilot update frontend --frontend-version latest
moviepilot update frontend --frontend-version v2.9.31

整体更新：

moviepilot update all
moviepilot update all --ref latest --frontend-version latest
moviepilot update all --skip-resources

说明：

• update backend 会更新 Git 仓库并重新安装后端依赖
• update frontend 会下载并替换前端 release
• update all 会同时更新后端、前端，默认也会同步资源文件
• 更新前请先执行 moviepilot stop

Agent 命令

直接给智能体发送一次请求：

moviepilot agent 帮我分析最近一次搜索失败的原因
moviepilot agent --user-id admin 帮我检查当前下载器配置
moviepilot agent --session cli-debug-1 帮我看看为什么没有自动整理
moviepilot agent --new-session 帮我总结当前系统配置有什么明显问题

说明：

• moviepilot agent 直接在本地环境里发起一次智能体请求
• 默认每次可自动创建新会话，也可以通过 --session 指定会话 ID
• 使用前需要先正确配置 LLM 相关参数，并打开 AI_AGENT_ENABLE

服务管理命令

moviepilot start/stop/restart/status 统一管理前后端。

启动、停止、重启与状态：

moviepilot start
moviepilot start --timeout 60
moviepilot stop
moviepilot stop --timeout 30 --force
moviepilot restart
moviepilot restart --start-timeout 60 --stop-timeout 30
moviepilot status
moviepilot version

说明：

• start 会先启动后端，再启动前端
• 如果开启了 MOVIEPILOT_AUTO_UPDATE=release|true|dev，start/restart 会在启动前尽力执行一次本地自动更新；更新失败只告警，不阻断当前启动
• 通过系统内置的重启入口触发重启时，本地 CLI 安装模式也会复用同一套前后端进程管理完成重启
• 前端默认监听 NGINX_PORT，默认值 3000
• 后端默认监听 PORT，默认值 3001
• 前端通过 service.js 代理 /api 与 /cookiecloud 到后端
• 本地前端代理在启动时会先确认后端可用；如果后端长时间不可用，前端也会自动退出，避免只剩半套服务

日志：

moviepilot logs
moviepilot logs --lines 100
moviepilot logs --stdio
moviepilot logs --frontend
moviepilot logs --follow
moviepilot logs --frontend --follow
moviepilot logs --stdio --follow

说明：

• 默认 logs 查看后端应用日志
• --stdio 查看后端启动标准输出
• --frontend 查看前端启动标准输出

配置命令

查看配置路径：

moviepilot config path

查看当前配置：

moviepilot config list
moviepilot config list --show-secrets

读取和写入单个配置：

moviepilot config get PORT
moviepilot config set PORT 3001
moviepilot config set NGINX_PORT 3000
moviepilot config set API_TOKEN your-token-here

查看所有可配置项：

moviepilot config keys
moviepilot config keys DB_
moviepilot config keys --show-current
moviepilot config keys --show-current --show-secrets
moviepilot config describe PORT
moviepilot config describe API_TOKEN --show-secrets

说明：

• config list 显示当前配置值
• config keys 显示配置项名称、类型和默认值
• config describe 显示单个配置项的类型、默认值和当前值

Tool 命令

列出所有 MCP 工具：

moviepilot tool list

查看单个工具的参数说明：

moviepilot tool show query_schedulers
moviepilot tool show search_torrents

运行工具：

moviepilot tool run query_schedulers
moviepilot tool run search_torrents media_type=movie tmdb_id=12345

说明：

• tool list 用于动态发现当前服务可调用的工具
• tool show 会输出参数名、类型和描述
• tool run 参数格式固定为 key=value

Scheduler 命令

列出调度任务：

moviepilot scheduler list

立即执行调度任务：

moviepilot scheduler run subscribe_refresh