boxyard-cli

Boxyard CLI

使用此技能来使用 Boxyard，而不是开发它：管理包含 DATA、元数据、同步配置、分组以及本地/rclone 存储的文件夹。以下所有捆绑路径均相对于此技能目录解析；无需检出源代码。

权限与安全

• 修改本地或远程状态前先征求批准。 这包括 init、 new、sync、multi-sync、sync-missing-meta、include、 exclude、relocate、delete、rename、sync-name、分组/父项编辑、 create-user-symlinks、copy、force-push、claim、release、discard-local， 以及非试运行模式的 convert。示例不代表已获授权。只读查询、--help、doctor 和 convert --dry-run 无需确认即可运行。
• 绝不在 ~/dev 中创建临时文件夹/克隆/工作树。 找到现有 box，或在获批后使用 boxyard new；将非 box 临时文件放在受管理根目录之外。 即使是大型生成数据，也要放在相关 box 内。使用同步排除项，而不是放在同级文件夹中，以免上传。
• 确认身份和位置，不要猜测。 时间戳格式和 subid 长度均可配置； index_name 为 {box_id}__{name}。使用 which/path： DATA 可能位于任何检出根目录，而不只是 user_boxes_path（default）。 根目录不可用时绝不会回退到默认值。存放位置仅限本机，不会同步到 boxmeta.toml； 远程存储和本地存放位置彼此独立。
• 确认所有权，绝不绕过。 DATA/CONF 推送会将 write_owner 与配置的 machine_name 进行比对，而非主机名。没有所有者限制时不受限制。 new 默认会认领（在其他位置工作时使用 --no-claim）；include --read-only 会抑制认领提醒。所有权限制也适用于 force-push、远程/双端重命名以及删除。 获批后，claim --steal 会保留本机的工作； discard-local 会从远程替换本地内容，并将被覆盖的工作保存在备份中。
• 破坏性操作陷阱： new --from PATH 会移动内容，除非使用 --copy；exclude 会先同步， 然后移除本地 DATA（--skip-sync 会跳过此保护）。 delete 会在整个设备群中将该 id 标记为已删除：绝不要删除名称过时的重复项 来清理注册记录。sync --sync-setting replace|force、copy --overwrite 和 force-push --force 可能覆盖数据。请先阅读相关参考资料。
• 备份不是垃圾： 孤立项可能是有意保留的 discard-local 备份。绝不要自动删除它们，也不要根据未认领的 ULID 推断它们可以丢弃。
• 排除项会替换，而非扩展。 box 的 conf/.rclone_exclude 会完全替换 默认列表：添加规则前先复制默认内容，否则可能导致 .venv/、node_modules/ 等被同步。 当前不接受 .rclone_include 和 .rclone_filters；请单独使用 .rclone_exclude。CONF 会先于 DATA 同步。 修改默认排除项会使整个设备群的 DATA 基线失效；需要修改时应批量处理。
• 转换需明确执行： 策略编辑不会重新格式化现有 box；只有 convert 会执行转换，并在移除旧副本前验证恢复后的内容与原内容逐字节一致。 在建议或更改 plain 与 restic 之间的选择前，请阅读存储参考资料和 ~/.config/myagent/reference/box-storage.md。 Rig 默认使用 plain；rclone 的软件包默认使用 restic（本地使用 plain）。使用 restic box 前， 每台参与的机器都需要安装 Boxyard >=0.7.0 和 restic，并准备好密码。

发现、选择、检查

以已安装的 CLI 为准：boxyard --help、boxyard <command> --help、 boxyard --version。如果当前已在 Boxyard 开发检出目录中操作， 优先使用 uv run boxyard ...；不要从已安装的 skill 目录相对导航来查找 源代码。使用非默认配置时，运行 boxyard --config /path/to/config.toml ...。 BOXYARD_CONFIG_PATH 供 shell helper 使用，不能替代 CLI 的 --config。

boxyard which --path /some/path --json
boxyard list --output-format json
boxyard list --show-status --show-checkout
boxyard list --group-filter 'work AND NOT archived'
boxyard checkout-roots
boxyard path --box INDEX_NAME
boxyard path --box INDEX_NAME --path-option conf
boxyard box-status --box INDEX_NAME
boxyard owner --box INDEX_NAME
boxyard yard-status
boxyard doctor --no-remote

• path 默认仅包含 DATA；--all 会纳入排除的候选项。对于非 DATA 位置，请使用 root、meta、conf 或 sync-record-* 选项。
• 使用 --box INDEX_NAME 或 --box-id BOX_ID 显式选择；--box-name NAME 通常表示名称包含匹配内容。只有在可以接受歧义时，才对 path 使用 --pick-first。不带参数的选择会先在所有已配置根目录中使用当前工作目录对应的 box， 然后显示 fzf 选择器；delete、rename、copy、force-push 和 sync-name 必须指定显式选择器。
• 状态看起来不一致时，运行 doctor，不要自行猜测如何修复。该命令为只读操作 （退出码 0 表示正常 / 1 表示发现问题）；默认包含远程检查，--no-remote 表示离线检查。 仅在获准更改状态后，才按照提示操作。

常见操作（获准后）

boxyard new --box-name NAME
boxyard new --from /path/to/folder --copy
boxyard include --box INDEX_NAME --checkout-root ROOT
boxyard sync --box INDEX_NAME --sync-setting careful
boxyard exclude --box INDEX_NAME
boxyard add-to-group --box INDEX_NAME GROUP

sync 可选择 META/CONF/DATA、同步方向和后代项。multi-sync 支持 周期设置和跳过证明；证明必须涵盖所有请求的部分及其依赖项，包括普通 DATA。 对于未知或未经证明的 box，仍会运行实际的同步流程。 执行迁移、破坏性恢复、转换或批量操作前，请先阅读对应参考文档和命令帮助。

任务到参考文档的映射（仅加载所需内容）

任务	随附参考文档
配置键、本地/远程布局、根目录、选择器、过滤器、规范发现	发现和路径
新建/包含/排除/复制、迁移、分组/层级、重命名/删除/强制操作	Box 生命周期
同步模式、多同步证明、周期设置、普通/restic 转换、排除项	同步和存储
所有者/认领/释放/丢弃本地状态以及 doctor 检查结果/恢复提示	所有权和健康状态
Ctrl+G、fzf、helper 搜索和 zsh 设置	Shell helper

软件包默认路径不等同于 rig 路径：请阅读实际配置（通常为 ~/.config/boxyard/config.toml），并使用 path。参考文档保留了详细示例和说明；历史数量不代表当前的集群清单。