文档

ReadShell 是终端里的书架：完全免费开源（MIT），本地优先，无需账号。

安装

需要 Node.js ≥ 20：

npm install -g readshell

novel import ~/books/
novel resume

命令

命令	说明
`novel import <path>`	导入书籍：支持 txt / epub / md，目录会递归扫描
`novel list`	列出书库中的所有书
`novel open <id>`	打开指定书籍
`novel resume`	从上次位置继续阅读（精确到字节）
`novel remove <id>`	从书库移除一本书
`novel lang zh\|en`	切换界面语言（中文 / English）
`novel config <key> <value>`	修改配置，见下方配置项
`novel update`	检查并更新到最新版本
`novel bookmarks export [--format json\|md] [--out file]`	导出书签为 JSON 或 Markdown
`novel stats`	终端热力图：近一年阅读天数、总时长、读完本数、当前连续天数
`novel sync --dir <path> [--with-books]`	设置同步文件夹并立即同步（--with-books 连书籍文件一起同步）
`novel sync`	用已保存的文件夹再同步一次
`novel sync --off`	关闭文件夹同步

快捷键

按键	操作
`Space / j / ↓ / f`	下一页
`k / ↑`	上一页
`g`	跳到开头
`G`	跳到结尾
`c`	章节列表与书签
`Tab`	切换目录 / 书签
`m`	添加书签
`b / Esc`	老板键：打印一段假的报错日志并退出，novel resume 精确回来
`q`	退出
`?`	显示帮助

配置项

用 novel config <key> <value> 修改：

key	取值	说明
`language`	zh \| en	界面语言
`line-spacing`	数字	行距
`reading-mode`	阅读模式	翻页 / 滚动等阅读模式
`boss-key-lang`	nodejs \| python \| java \| c \| go	老板键伪装成哪种语言的报错

novel config language zh
novel config boss-key-lang go

文件夹同步

ReadShell 没有自己的服务器。同步的原理很简单：把数据文件放进一个已经被云盘同步的文件夹，剩下的交给 iCloud / Dropbox / OneDrive / 坚果云 / Syncthing。打开阅读器时自动拉取最新进度，退出时自动推送；同步失败静默处理，绝不打断阅读。

设置一次即可：

# iCloud Drive（macOS）
novel sync --dir "~/Library/Mobile Documents/com~apple~CloudDocs/readshell"

# Dropbox
novel sync --dir ~/Dropbox/readshell

# OneDrive
novel sync --dir ~/OneDrive/readshell

# 坚果云
novel sync --dir ~/Nutstore/readshell

# Syncthing：指向你同步的任意本地文件夹
novel sync --dir ~/Sync/readshell

· 加 --with-books 可以把书籍文件也一起同步（默认只同步进度、书签和统计）。

· 之后随时运行 novel sync 手动同步一次。

· novel sync --off 关闭同步，本地数据不受影响。

从 readshell-pro 迁移

1.0 起 Pro 版与开源版合并为同一个完全免费的 readshell 包。旧的 readshell-pro 已停止维护，请切换到新包：

npm uninstall -g readshell-pro
npm install -g readshell

本地书库、进度和书签保存在本机数据目录中，切换包名不会丢失。原来依赖云同步的，改用 novel sync --dir 文件夹同步即可。

常见问题

真的完全免费吗？

是的。ReadShell 1.0 起全部功能以 MIT 协议开源，没有付费版、没有账号、没有内购。

我的数据存在哪里？会被上传吗？

所有数据（书库、进度、书签、统计）都在本地 SQLite 文件里。ReadShell 没有任何服务器，永远不会上传任何东西。

多设备怎么同步？

用 novel sync --dir 指向一个被 iCloud / Dropbox / OneDrive / 坚果云 / Syncthing 同步的文件夹即可。打开阅读器时自动拉取，退出时自动推送，失败静默不打扰。

老板键安全吗？

按下 b 或 Esc 后屏幕立刻变成一段逼真的报错日志（可选 Node.js / Python / Java / C / Go 风格），日志里不含任何你的个人路径。安全后运行 novel resume 精确回到原位。

支持哪些格式？

txt、epub、md。novel import 传入目录时会递归扫描所有支持的文件。