douban-cli

Unofficial Douban CLI for movies, TV shows, books, collections, and authenticated movie actions.

在终端里浏览豆瓣电影、剧集、图书和用户收藏，也可以登录后管理自己的电影记录。

douban-cli 不只是一个搜索命令：它覆盖影视发现、Top250 与口碑榜、电影和图书详情、评分分布、短评/长评/读书笔记、公开片单与书单、交互翻页、JSON 输出、批量标记和数据导出。

公开电影、图书、豆列和用户收藏查询无需登录。只有账号身份、电影标记/评分/评论、个人统计与私有导出需要显式运行 douban login。

当前登录后的写操作仅支持电影；图书功能为公开查询、阅读内容和公开书单导出。

导航： 快速开始 · 电影与剧集 · 图书 · 用户收藏 · 账号操作 · 批量操作 · JSON

✨ 功能亮点

• 🎬 电影与剧集发现：热门、剧集标签、类型排行、电影 Top250、即将上映、一周口碑榜。
• 🔎 条目深度查询：电影支持 ID 或片名；图书支持豆瓣 ID、ISBN 或关键词自动解析。
• 📚 完整图书链路：图书 Top250、当前热门榜、新书速递、搜索、评分、短评、书评、读书笔记。
• 🗂️ 用户收藏与导出：查看公开的想看/在看/看过、想读/在读/读过，并导出书单或个人观影记录。
• 🔐 登录后账号操作：标记、评分、短评、长评、关注和观影统计；支持批量文件。
• 🤖 适合脚本化和 AI 分析：多数命令支持 --json，个人影音记录可导出为结构化数据，错误也提供稳定的结构化输出。
• ⌨️ 终端友好：表格输出、加载状态、交互翻页、已访问页面缓存，以及 partial result warning。

🚀 快速开始

# 发现一部电影
douban hot
douban rank 科幻 --limit 10
douban movie "沙丘"

# 找一本书并继续查看内容
douban book search "三体"
douban book info 9787536692930
douban book comments 三体

# 查看或导出公开收藏
douban user USER_ID --wish
douban book user USER_ID --reading
douban book export USER_ID --wish -o books.md

# 给脚本消费
douban search "奥本海默" --json

📦 安装

需要 Node.js 22.13.0 或更高版本。

npm install -g @marvae24/douban-cli

安装后使用 douban：

douban hot
douban --help
douban book --help

也可以不安装，直接通过 npx 运行：

npx @marvae24/douban-cli hot

🎬 电影与剧集

这一组命令都是公开只读请求，无需登录，并且全部支持 --json。

| 命令 | 能做什么 | 常用参数 | |---|---|---| | douban hot | 热门电影；加 --tv 查看剧集 | --tv、--tag、--limit | | douban tv <tag> | 按标签查看剧集 | 热门/美剧/英剧/日剧/韩剧/国产剧/综艺/最新 | | douban rank <genre> | 按类型查看高分电影 | --limit | | douban top250 | 豆瓣电影 Top250，每页 25 条 | --page，支持交互翻页 | | douban coming | 即将上映 | --limit | | douban weekly | 一周口碑榜与排名趋势 | --limit | | douban search <keyword> | 搜索电影 | --start、--limit | | douban movie <id-or-title> | 电影/剧集详情，可直接传 ID 或片名 | --json | | douban rating <id> | 评分分布、想看/看过统计和类型排名 | 只接受数字 ID | | douban comments <id> | 热门短评 | --page、--limit | | douban reviews <id> | 热门影评 | --page、--limit |

类型排行支持：剧情、喜剧、动作、爱情、科幻、动画、悬疑、惊悚、恐怖、纪录片、短片、情色、同性、音乐、歌舞、家庭、儿童、传记、历史、战争、犯罪、西部、奇幻、冒险、灾难、武侠、古装、运动、黑色电影。

douban hot --tv --tag 英剧 --limit 10
douban top250 --page 2
douban search "奥本海默" --start 20 --limit 20
douban movie 35593344
douban movie "沙丘"
douban rating 1291546
douban comments 1291546
douban reviews 1291546 --limit 5

电影详情会尽量展示中文名/原名、年份、评分、评分人数、导演、编剧、主演、类型、制片国家/地区、语言、片长、上映日期、别名、IMDb、集数、简介和评分分布。上游部分来源不可用时，CLI 会合并仍然可用的数据。

📚 图书

图书命令都是公开只读请求，无需登录。详情、评分、短评、书评和笔记命令均可接受豆瓣条目 ID、ISBN 或关键词。

| 命令 | 能做什么 | 常用参数 | |---|---|---| | douban book hot | 旧版兼容入口，等同图书 Top250 | --start、--limit | | douban book top250 | 豆瓣图书 Top250 | --start、--limit | | douban book chart [category] | 当前热门图书榜，最多 20 条 | --limit | | douban book new [category] | 新书速递，最多 20 条 | --limit；别名 latest | | douban book search <keyword> | 按书名、作者或 ISBN 搜索 | --start、--limit | | douban book info <query> | 图书完整详情 | ID、ISBN 或关键词 | | douban book rating <query> | 五星分布与想读/在读/读过统计 | ID、ISBN 或关键词 | | douban book comments <query> | 热门短评 | --page、--limit | | douban book reviews <query> | 热门书评 | --page、--limit | | douban book notes <query> | 热门读书笔记 | --page、--limit | | douban book user <userId> | 公开的想读/在读/读过书单 | --wish、--reading、--page、--limit | | douban book export <userId> | 将公开书单导出到文件 | --wish、--reading、--limit、--output、--format、--delay |

book chart 和 book new 支持：全部、文学、小说、历史文化、社会纪实、科学新知、艺术设计、商业经管、绘本漫画。

# 榜单与发现
douban book chart 小说 --limit 10
douban book top250 --start 25 --limit 20
douban book latest 科学新知

# 搜索、详情与内容
douban book search "三体" --limit 20
douban book info 三体
douban book info 9787536692930
douban book rating 三体
douban book comments 三体
douban book reviews 三体 --limit 5
douban book notes 三体 --limit 5

# 公开书单
douban book user USER_ID --wish --page 2
douban book user USER_ID --reading
douban book export USER_ID --wish --limit 100 --delay 2 -o books.md
douban book export USER_ID --reading -f csv -o reading.csv

图书详情覆盖作者、译者、出版社、出品方、出版年、页数、装帧、定价、ISBN、丛书、标签、电子书、短评/书评/笔记数量、内容简介、作者简介和目录等字段。字段来自多个公开来源，某个来源失败时仍会保留其他来源的结果。

🗂️ 用户收藏、豆列与配置

| 命令 | 能做什么 | 登录要求 | |---|---|---| | douban user <userId> | 指定用户的电影看过/想看/在看 | 无需登录；默认看过，使用 --wish 或 --doing 切换 | | douban book user <userId> | 指定用户的图书读过/想读/在读 | 无需登录；默认读过，使用 --wish 或 --reading 切换 | | douban config | 查看本地配置；--user <id> 设置 me 的默认用户 | 无需登录 | | douban me | 默认用户或当前登录账号的电影收藏 | 配置过用户 ID 时无需登录，否则使用缓存登录态 | | douban list | 热门豆列推荐 | 无需登录 |

douban user USER_ID
douban user USER_ID --wish --page 2
douban user USER_ID --doing

douban config --user USER_ID
douban config
douban me --wish
douban list --limit 10

🔐 登录、个人数据与账号操作

首次使用账号功能时运行：

douban login
douban whoami

login 默认不会启动浏览器。它会识别系统默认浏览器，说明即将读取的来源，并在你确认后只读取一次豆瓣所需的 dbcl2 / ck Cookie。浏览器已有登录态时无需再次输入账号密码；尚未登录时可加 --open 打开当前账号页。多浏览器或多账号环境可以明确选择来源：

douban login --browser arc
douban login --open
douban login --browser chrome --profile "Profile 2"
douban login --browser chrome --cookie-timeout 120

未传 --browser 时，CLI 会识别系统 HTTPS 默认浏览器，只从同一个来源读取 Cookie，避免扫描多个浏览器和重复触发钥匙串授权。只有显式传入 --open 才会启动该浏览器并打开豆瓣当前账号页；这个窗口只是登录入口，最终保存哪个账号以 Cookie 验证结果为准。--open 不能与 --profile 同用：需要指定 profile 时，请先手动打开该 profile，再运行不带 --open 的登录命令。--browser 支持 Chrome、Edge、Firefox、Safari 和 Arc，其中 Safari 与 Arc 仅支持 macOS。--profile 必须与 --browser 一起使用，Safari 不支持指定 profile。浏览器 Cookie 和系统钥匙串默认等待 60 秒，可用 --cookie-timeout 调整为 1-300 秒。浏览器模式需要交互式终端，不能通过管道或 CI 启动。macOS 首次读取 Chromium 浏览器登录态时可能弹出 Safe Storage 授权，请选择允许。

浏览器提取不可用时，可以显式选择一种手动导入方式：

# macOS：先在浏览器开发者工具中复制单行 Cookie 请求头
pbpaste | douban login --cookie-stdin

# Windows PowerShell
Get-Clipboard | douban login --cookie-stdin

# 浏览器扩展导出的 Netscape cookies.txt
douban login --cookie-file /path/to/douban-cookies.txt

--cookie-stdin 只接受非交互式标准输入中的单行 Cookie 请求头，可带 Cookie: 前缀和一个末尾换行；--cookie-file 只接受普通的 Netscape cookies.txt 文件。两者互斥，也不能与浏览器登录参数混用。CLI 只保留 dbcl2 / ck，验证对应豆瓣账号后才写入加密缓存；即使浏览器提取失败，也不会自动读取标准输入、文件、剪贴板或环境变量。不要把 Cookie 放进命令行参数、环境变量、聊天、Issue 或日志；导入文件本身也是登录凭据，使用后应妥善删除或限制访问。login --json 只输出来源和账号信息，不输出或遮罩展示任何 Cookie。

登录缓存会加密保存在本地，账号写操作前会重新核对身份。

电影标记、评分与评论

以下操作会修改当前豆瓣账号，而且目前只支持电影：

douban mark 1292052 --wish
douban mark 1292052 --watched
douban mark 1292052 --watching
douban unmark 1292052

douban rate 1292052 --score 5
douban comment 1292052 "值得二刷"
douban review 1292052 "标题" "长评正文"
douban review 1292052 "标题" --file review.md

rate 和 comment 会按“看过”状态提交。mark 的 --wish、--watched、--watching 三种状态必须且只能选择一个。

统计、导出与关注

douban stats --year 2026 --limit 30 --delay 2
douban export --format json -o douban-export.json
douban export --format csv -o douban-export.csv

douban follow USER_ID
douban unfollow USER_ID
douban logout

stats 默认基于最近最多 1000 条“看过”记录统计总数、月份分布和平均分，因此较早年份可能不完整；可用 --limit 调整读取量。stats、账号 export 和 book export 默认在分页请求之间等待 1 秒，可用 --delay 调整。账号 export --delay 同时用于同一状态的分页和看过/想看/在看三种状态之间；其 --limit 分别应用于三种状态，总条数最多可能接近 3 × limit。

📦 两种导出

| 命令 | 数据 | 登录 | 格式 | 说明 | |---|---|---|---|---| | douban book export <userId> | 指定用户的公开想读/在读/读过 | 不需要 | Markdown、CSV、JSON | 必须指定 --output；未传 --format 时按扩展名推断；最多 5000 条；--delay 控制分页间隔 | | douban export | 当前账号的电影看过/想看/在看 | 需要 | CSV、JSON | 必须指定 --output；可能包含评分、短评和用户信息；--delay 控制分页和状态切换间隔 |

两种导出在后续页面请求失败时都会保留已经取得的数据，并通过 stderr 明确告警。JSON 文件还会写入 metadata.partial 和 metadata.warnings；CSV/Markdown 会在完成提示中标明结果可能不完整。

🧰 批量操作

电影标记、取消标记、评分和短评支持 --file。默认在每次写入之间随机等待 1–2 秒，也可以通过 --delay 指定固定间隔。

douban mark --file ids.txt --wish
douban unmark --file ids.txt --delay 1.5
douban rate --file ratings.csv
douban comment --file comments.tsv --delay 1.5

文件格式：

• mark / unmark：每行一个电影 ID。
• rate：每行 <id>,<score>，score 为 1–5。
• comment：每行 <id>,<comment>，逗号或制表符分隔。
• 空行和以 # 开头的注释会被忽略。

批量任务会逐项继续执行；如果部分条目失败，结果会同时给出成功和失败明细，并以非零退出码结束。

🤖 JSON 输出与脚本化

除两个文件导出命令外，所有操作命令都支持 --json：

douban weekly --json
douban book info 三体 --json
douban user USER_ID --wish --json
douban whoami --json

• --json 将命令结果写到 stdout；失败时向 stderr 写结构化 JSON，并返回非零退出码。
• export --format json 与 book export --format json 是文件格式选项，不会把 JSON 打到 stdout。
• 需要稳定脚本行为时，以具体命令的 --help 和 JSON 字段为准，不要解析人类可读表格。

⌨️ 交互翻页

以下命令在交互终端中支持翻页：

• 电影：top250、comments、reviews、user。
• 图书：book comments、book reviews、book notes、book user。

按回车或 n 下一页，p 上一页，g <页码> 跳转，q 退出。已经访问过的页面会在本次会话中复用。

使用 --json、管道或重定向时不会进入交互模式，只返回 --page 指定的页面。search、book search 和 book top250 使用 --start 偏移量，不使用交互分页。

🛡️ 登录与隐私

• 公开只读命令不会隐式读取浏览器 Cookie。浏览器登录只在显式运行 douban login 时发生；手动导入只在显式传入 --cookie-stdin 或 --cookie-file 时发生，浏览器失败不会自动切换来源。
• CLI 不接受包含 Cookie 内容的命令行参数或环境变量，也不会自行读取剪贴板。Netscape cookies.txt 属于敏感登录凭据，不要提交到 Git、上传到公开服务或长期保留。
• 登录缓存使用 AES-256-GCM 加密、文件权限 0600，应用目录权限为 0700，并按缓存内的 updatedAt 在 30 天后失效；douban logout 会删除本地缓存，不会退出浏览器中的豆瓣账号。
• macOS 将登录缓存和配置保存在 ~/Library/Application Support/douban-cli/；Linux 分别使用 $XDG_STATE_HOME/douban-cli/ 和 $XDG_CONFIG_HOME/douban-cli/（未设置时使用标准默认目录）；Windows 分别使用 %LOCALAPPDATA%\douban-cli\ 和 %APPDATA%\douban-cli\。
• 可将 DOUBAN_CLI_HOME 设为绝对路径，让登录缓存和配置统一存放到指定目录。旧的 ~/.douban-cli-auth.json 与 ~/.douban-cli.json 会在验证迁移结果后自动删除。
• 多浏览器登录不同账号时，请使用 --browser 和 --profile 明确选择，避免操作错误账号。
• 导出文件可能包含用户 ID、收藏、评分和短评。请保存到合适的位置，不要误提交到 Git 或上传到公开服务。

🩺 排查问题

先查看根命令或子命令帮助：

douban --help
douban book --help
douban book comments --help

需要排查网络、解析或登录问题时，可以临时启用调试日志：

DOUBAN_DEBUG=1 douban book info 三体

豆瓣页面可能出现限流、验证码或结构变化。CLI 会对只读 GET 请求进行有限重试，并尽量返回已经取得的 partial results；如果页面结构无法可靠识别，会明确报错而不是把解析失败伪装成空列表。

🧪 开发

npm ci
npm run verify

npm run verify 会依次执行 lint、源代码与测试类型检查、单元测试、构建和 CLI smoke tests。

License

MIT