命令行选项

markon 是 markond 后台服务的本地客户端。它负责解析配置、启动或连接服务、注册 Workspace，并通过当前用户专属的本地控制套接字执行管理操作。

安装

cargo install markon markond

两个二进制都应位于 PATH。缺少 markond 时，markon 会在当前进程以前台模式提供服务。

语法

markon [OPTIONS] [FILE]
markon <COMMAND>

FILE 可以是 Markdown 文件或目录；省略时使用当前目录。传入路径后默认尝试打开浏览器。

桌面版用户

桌面版 Tips 页提供 CLI 命令生成器，可根据路径、地址与访问码生成命令或 shell alias。

主选项

选项	代码中的行为
-p, --port <PORT>	Web 端口，默认 6419；显式参数覆盖 settings
--host [IP]	指定绑定地址；只写 --host 时进入网卡选择器
--public-base-url [URL]	对外 HTTP(S) 基础 URL，用于生成链接、二维码及允许的来源；保存为默认值
--trusted-host <HOST_OR_ORIGIN>	额外允许的精确 authority，可重复
-b, --open-browser [URL]	打开浏览器；无值用本地地址，有值时用给定 base
--collaborator-access-code <CODE>	设置当前工作区协作者码；空字符串清除
--print-collapsed-content	打印时强制包含折叠正文；默认显示折叠占位
--salt <SALT>	高级 workspace-id salt 覆盖；已有安装不要随意修改

功能开关不再是启动参数。使用 markon set、桌面端或浏览器管理员页调整。

子命令

markon ls

markon ls
markon ls --format cards
markon ls --format table

• stdin/stdout 都是可用 TTY 时，裸命令启动交互式 TUI。
• 非 TTY 或 MARKON_NO_TUI 已设置时，回退为静态 cards。
• --format 可明确要求 cards 或 table。

结果包含 workspace id/path、功能开关、Search ready 状态、本地/公网地址与 QR 信息。TUI 还能编辑功能、打开 Workspace、分享已开启 Shared 的协作者地址，以及进入数据清理。

markon set

markon set <ID|INDEX> <FEATURE> <on|off>

FEATURE：

值	功能
search	Tantivy/Jieba 内容索引与 Spotlight 搜索结果
viewed	H2–H6 Viewed 状态和章节动作
edit	CodeMirror 保存与 AI edit_file 提案
live	Broadcast / Follow
chat	Workspace AI
shared	协作者读写批注/Viewed，并通过 WebSocket 同步

示例：

markon set 1 edit on
markon set a1b2c3d4 chat off

markon detach

markon detach <ID|INDEX>

从运行中注册表移除 Workspace，并持久化列表。不会删除源文件、settings 其它字段或 SQLite 历史。

markon cleanup

markon cleanup
markon cleanup --yes

统计并可选删除不属于任何活动 Workspace 的 annotations、Viewed 与 Chat 数据。执行前请先读数据与隐私并备份数据库。

markon admin

markon admin open
markon admin code

• open：创建 60 秒有效、一次性 URL fragment nonce 并打开浏览器；
• code：打印 5 分钟有效的手动配对码，适合 SSH/headless。

两者兑换相同的短期 HttpOnly Admin session。loopback 不自动获得管理员角色。

markon shutdown

请求后台服务优雅关闭并清理运行锁。

markon bug / idea / ask

markon bug  [-t TITLE] [-b BODY]
markon idea [-t TITLE] [-b BODY]
markon ask  [-t TITLE] [-b BODY]

通过已认证的 gh 创建 GitHub Issue 或 Discussion；未提供 title/body 时进入交互输入或 $EDITOR。

单服务、多工作区

markon project-a/
markon project-b/
markon README.md
markon ls

第一次调用启动 markond，之后的调用连接现有服务。目录工作区写入 settings 并恢复；单文件工作区是否自动清理由全局设置控制。

若运行中的服务版本与当前 CLI 不兼容，CLI 会刷新服务状态，而不是把新客户端命令发给旧控制协议。

地址与浏览器行为

markon README.md                 # 路径参数：默认尝试打开
markon                           # 当前目录：默认不强制打开
markon -b                        # 当前目录并打开本地地址
markon -b https://docs.example.com docs/

--open-browser URL 会把 Workspace 路径附加到给定 base，适合反向代理入口。

对外基础 URL 与持久化

--public-base-url 设置对外访问的 HTTP(S) 基础 URL，例如 https://md.example.com 或 http://192.168.1.20:6419。必须包含协议，不能只写域名，也不要填具体文档的完整链接；Markon 会自动追加工作区和文件路径。

--open-browser 设置本次打开浏览器的行为。两者可以使用不同地址：

# 分享使用域名，本机浏览器使用本地地址
markon docs/ --public-base-url https://md.example.com --open-browser

# 本机浏览器也使用域名
markon docs/ --open-browser https://md.example.com

# 清除保存的对外地址，恢复自动选择本地／局域网地址
markon --public-base-url "" ls

显式传入的对外基础 URL 会写入 ~/.markon/settings.json 的 public_base_url 字段，后续调用、服务重启和桌面端都使用它。旧配置中的 public_url 会自动沿用；两个字段都缺少时默认为空。也可以在已有配置中将 public_base_url 字段设为所需的 HTTP(S) URL，保留其它字段。

修改保存的对外地址后，下一次 CLI 调用会按需刷新后台服务，更新访问白名单，同时保留当前工作区、端口和监听地址。markon admin code 也使用该对外地址。浏览器默认仍使用本地地址；--open-browser URL 仅覆盖本次打开地址，不写入配置。

兼容旧脚本：--public-url、--entry、--qr 仍是 --public-base-url 的别名。旧配置中的 public_url 字段仍可读取，写回时改用 public_base_url。只写 --public-base-url 而不提供 URL，会为本次调用生成本地二维码，不修改已保存的默认值。

监听示例

markon docs/                     # 默认 settings host；新安装通常是 127.0.0.1
markon docs/ --host              # 交互选择网卡
markon docs/ --host 0.0.0.0      # 全接口
markon docs/ --host 192.168.1.5  # 指定接口

局域网：

markon docs/ --host 0.0.0.0 \
  --public-base-url http://192.168.1.20:6419 \
  --collaborator-access-code guest-secret

反向代理：

markon docs/ --host 127.0.0.1 \
  --public-base-url https://docs.example.com \
  --trusted-host https://docs.example.com

--public-base-url 设置对外基础 URL，并登记其中的 origin；不提供 TLS。公网部署见反向代理。

设置优先级

CLI 读取 ~/.markon/settings.json。大体规则是：

1. 本次显式命令行参数；
2. 已保存全局设置；
3. 内置默认值。

主题、语言、自定义样式、快捷键、Provider、工作区列表和新工作区默认开关与桌面端共享。运行中 Workspace 注册表由服务拥有，GUI 保存偏好时不会用旧快照覆盖它。

数据库覆盖

MARKON_SQLITE_PATH=/srv/markon/annotation.sqlite markon docs/

数据库保存批注、Viewed 与 Chat。是否启用 Shared 不改变存储位置，只改变协作者能力与广播。