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 --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
• 前端启动日志：<Config Dir>/logs/moviepilot.frontend.stdout.log

帮助与发现

根帮助：

moviepilot --help
moviepilot help
moviepilot commands

分级帮助：

moviepilot help install
moviepilot help init
moviepilot help setup
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 update backend
moviepilot update frontend
moviepilot update all
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 --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 --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 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 会先启动后端，再启动前端
• 通过系统内置的重启入口触发重启时，本地 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