boxyard-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Boxyard CLI Skill

Boxyard CLI 技能

Use this skill when the user wants to use Boxyard, not develop Boxyard itself.

Boxyard is a Python CLI for managing and syncing folders ("boxes") across local and remote storage using rclone or local storage. A box has data, metadata, optional sync configuration, group membership, and sync records.

当用户想要使用Boxyard而非开发Boxyard本身时，使用本技能。

Boxyard是一款Python CLI工具，可通过rclone或本地存储在本地与远程存储之间管理和同步文件夹（即"boxes"）。每个box包含数据、元数据、可选的同步配置、组归属以及同步记录。

Before running commands

运行命令前的注意事项

If operating from this repository checkout, prefer:
bash
```
cd /path/to/boxyard && uv run boxyard ...
```
If Boxyard is already installed in the environment,
```
boxyard ...
```
is also fine.
Read-only commands are safe to run without confirmation:
```
--help
```
,
```
list
```
,
```
tree
```
,
```
path
```
,
```
which
```
,
```
box-status
```
,
```
yard-status
```
,
```
list-groups
```
.

Ask before running commands that can modify local or remote state:

init

new

sync

multi-sync

sync-missing-meta

include

exclude

delete

rename

sync-name

add-to-group

remove-from-group

add-parent

remove-parent

create-user-symlinks

copy

force-push

Be especially careful with:
- ```
boxyard new --from PATH
```
  /
```
-f PATH
```
  : moves
```
PATH
```
  into Boxyard unless
```
--copy
```
  is supplied.
- ```
boxyard exclude
```
  : syncs first by default, then removes the local data copy.
- ```
boxyard delete
```
  : deletes a box.
- ```
boxyard sync --sync-setting replace|force
```
  : can overwrite data depending on direction/status.
- ```
boxyard force-push --force
```
  : destructively overwrites remote data from a local source folder.

如果从本代码库检出目录操作，优先使用：
bash
```
cd /path/to/boxyard && uv run boxyard ...
```
如果环境中已安装Boxyard，直接使用
```
boxyard ...
```
也可。
只读命令无需确认即可安全运行：
```
--help
```
、
```
list
```
、
```
tree
```
、
```
path
```
、
```
which
```
、
```
box-status
```
、
```
yard-status
```
、
```
list-groups
```
。

运行可能修改本地或远程状态的命令前需先询问用户：

init

、

new

、

sync

、

multi-sync

、

sync-missing-meta

、

include

、

exclude

、

delete

、

rename

、

sync-name

、

add-to-group

、

remove-from-group

、

add-parent

、

remove-parent

、

create-user-symlinks

、

copy

、

force-push

。

尤其需要注意以下命令：
- ```
boxyard new --from PATH
```
  /
```
-f PATH
```
  ：除非提供
```
--copy
```
  参数，否则会将
```
PATH
```
  移动到Boxyard中。
- ```
boxyard exclude
```
  ：默认先同步，然后删除本地数据副本。
- ```
boxyard delete
```
  ：删除一个box。
- ```
boxyard sync --sync-setting replace|force
```
  ：根据同步方向/状态可能会覆盖数据。
- ```
boxyard force-push --force
```
  ：从本地源文件夹破坏性地覆盖远程数据。

Configuration files and important paths

配置文件与重要路径

Default files and folders:

text

~/.config/boxyard/config.toml          # main Boxyard config
~/.config/boxyard/boxyard_rclone.conf  # Boxyard's rclone config
~/.config/boxyard/default.rclone_exclude
~/.boxyard/                            # default boxyard_data_path
~/boxes/                               # default user_boxes_path; included box data appears here
~/box-groups/                          # default user_box_groups_path; group symlinks appear here

The config file controls the real locations. Important config keys:

toml

default_storage_location = "..."
boxyard_data_path = "~/.boxyard"
user_boxes_path = "~/boxes"
user_box_groups_path = "~/box-groups"
max_concurrent_rclone_ops = 3

[storage_locations.my-remote]
storage_type = "rclone" # or "local"
store_path = "boxyard"

Derived paths:

text

<boxyard_data_path>/boxyard_meta.json          # cached local box index
<boxyard_data_path>/local_store/<storage>/     # local metadata/conf roots by storage location
<boxyard_data_path>/sync_records/              # local sync records
<boxyard_data_path>/sync_backups/              # local sync backups
<boxyard_data_path>/remote_indexes/            # cached remote index lookups

For a box with index name

<box_id>__<name>

text

<user_boxes_path>/<box_id>__<name>/                         # data path for included boxes
<boxyard_data_path>/local_store/<storage>/<index>/           # local box root
<boxyard_data_path>/local_store/<storage>/<index>/boxmeta.toml
<boxyard_data_path>/local_store/<storage>/<index>/conf/

Remote/rclone stores use this layout under the storage location's

store_path

text

boxes/<index>/data/
boxes/<index>/boxmeta.toml
boxes/<index>/conf/
sync_records/<index>/<data|meta|conf>.rec
sync_backups/

The global CLI option for non-default config is:

bash

boxyard --config /path/to/config.toml <command> ...

boxyard init

uses

--config-path

and

--data-path

to create a config/data directory. The shell helper honors

BOXYARD_CONFIG_PATH

; normal Typer CLI commands should be given

--config

when using a non-default config.

DEFAULT_BOX_GROUPS

can add default groups at runtime. It is parsed as a TOML list string, for example:

bash

export DEFAULT_BOX_GROUPS='["ctx/mac", "work"]'

默认文件和文件夹：

text

~/.config/boxyard/config.toml          # Boxyard主配置文件
~/.config/boxyard/boxyard_rclone.conf  # Boxyard的rclone配置文件
~/.config/boxyard/default.rclone_exclude
~/.boxyard/                            # 默认boxyard_data_path
~/boxes/                               # 默认user_boxes_path；已包含的box数据存放在此
~/box-groups/                          # 默认user_box_groups_path；组符号链接存放在此

配置文件控制实际路径位置，重要配置项：

toml

default_storage_location = "..."
boxyard_data_path = "~/.boxyard"
user_boxes_path = "~/boxes"
user_box_groups_path = "~/box-groups"
max_concurrent_rclone_ops = 3

[storage_locations.my-remote]
storage_type = "rclone" # 或 "local"
store_path = "boxyard"

衍生路径：

text

<boxyard_data_path>/boxyard_meta.json          # 缓存的本地box索引
<boxyard_data_path>/local_store/<storage>/     # 按存储位置划分的本地元数据/配置根目录
<boxyard_data_path>/sync_records/              # 本地同步记录
<boxyard_data_path>/sync_backups/              # 本地同步备份
<boxyard_data_path>/remote_indexes/            # 缓存的远程索引查询结果

对于索引名称为

<box_id>__<name>

的box：

text

<user_boxes_path>/<box_id>__<name>/                         # 已包含box的数据路径
<boxyard_data_path>/local_store/<storage>/<index>/           # 本地box根目录
<boxyard_data_path>/local_store/<storage>/<index>/boxmeta.toml
<boxyard_data_path>/local_store/<storage>/<index>/conf/

远程/rclone存储在其存储位置的

store_path

下使用以下布局：

text

boxes/<index>/data/
boxes/<index>/boxmeta.toml
boxes/<index>/conf/
sync_records/<index>/<data|meta|conf>.rec
sync_backups/

使用非默认配置的全局CLI选项：

bash

boxyard --config /path/to/config.toml <command> ...

boxyard init

使用

--config-path

和

--data-path

创建配置/数据目录。Shell辅助工具会识别

BOXYARD_CONFIG_PATH

环境变量；使用非默认配置时，常规Typer CLI命令需指定

--config

参数。

DEFAULT_BOX_GROUPS

可在运行时添加默认组，它会被解析为TOML列表字符串，例如：

bash

export DEFAULT_BOX_GROUPS='["ctx/mac", "work"]'

How to find where boxes are

如何查找box的位置

Use these patterns first.

优先使用以下方式。

Find the box containing the current directory or any path

查找包含当前目录或任意路径的box

bash

boxyard which
boxyard which --path /some/path
boxyard which --path /some/path --json
boxyard which --path /some/path --index-name

which

reports the box name, box id, index name, storage location, groups, local data path, and whether the box is included.

bash

boxyard which
boxyard which --path /some/path
boxyard which --path /some/path --json
boxyard which --path /some/path --index-name

which

命令会返回box名称、box ID、索引名称、存储位置、所属组、本地数据路径以及该box是否已被包含。

Get a box's data folder

获取box的数据文件夹

bash

boxyard path --box-name NAME --pick-first
boxyard path --box-id BOX_ID
boxyard path --box INDEX_NAME

boxyard path

defaults to the data path. By default it filters to included boxes. Use

--all

when you need to select from included and excluded boxes.

Interactive selector:

bash

boxyard path --interactive
boxyard path -I --browse-mode groups
boxyard path -I --browse-mode tree

bash

boxyard path --box-name NAME --pick-first
boxyard path --box-id BOX_ID
boxyard path --box INDEX_NAME

boxyard path

默认返回数据路径，默认仅筛选已包含的box。若需从已包含和已排除的box中选择，使用

--all

参数。

交互式选择器：

bash

boxyard path --interactive
boxyard path -I --browse-mode groups
boxyard path -I --browse-mode tree

Get non-data paths for a box

获取box的非数据路径

bash

boxyard path --box-name NAME --pick-first --path-option root
boxyard path --box-name NAME --pick-first --path-option meta
boxyard path --box-name NAME --pick-first --path-option conf
boxyard path --box-name NAME --pick-first --path-option sync-record-data
boxyard path --box-name NAME --pick-first --path-option sync-record-meta
boxyard path --box-name NAME --pick-first --path-option sync-record-conf

bash

boxyard path --box-name NAME --pick-first --path-option root
boxyard path --box-name NAME --pick-first --path-option meta
boxyard path --box-name NAME --pick-first --path-option conf
boxyard path --box-name NAME --pick-first --path-option sync-record-data
boxyard path --box-name NAME --pick-first --path-option sync-record-meta
boxyard path --box-name NAME --pick-first --path-option sync-record-conf

Find the top-level included boxes folder

查找顶级已包含box文件夹

Read

user_boxes_path

from the config. Included boxes are usually symlinked or stored under:

text

~/boxes/<index_name>

Commands:

bash

boxyard list --show-status
boxyard path --box INDEX_NAME

●

means included locally;

○

means known metadata exists but local data is excluded/not present.

从配置文件中读取

user_boxes_path

。已包含的box通常以符号链接形式或存储在：

text

~/boxes/<index_name>

Common discovery commands

常用发现类命令

bash

boxyard list
boxyard list --show-status
boxyard list --output-format json
boxyard list --view groups --show-status
boxyard list --view tree --show-status
boxyard tree --show-status
boxyard list-groups --all --include-virtual
boxyard yard-status

Group filters support boolean expressions over group names:

bash

boxyard list --group-filter 'work AND NOT archived'
boxyard path --group-filter 'ctx/mac OR ctx/linux' --interactive

Other list filters:

bash

boxyard list --include-group GROUP
boxyard list --exclude-group GROUP
boxyard list --children-of BOX
boxyard list --descendants-of BOX
boxyard list --parent-of BOX
boxyard list --ancestors-of BOX
boxyard list --roots
boxyard list --leaves

bash

boxyard list
boxyard list --show-status
boxyard list --output-format json
boxyard list --view groups --show-status
boxyard list --view tree --show-status
boxyard tree --show-status
boxyard list-groups --all --include-virtual
boxyard yard-status

组筛选器支持基于组名称的布尔表达式：

bash

boxyard list --group-filter 'work AND NOT archived'
boxyard path --group-filter 'ctx/mac OR ctx/linux' --interactive

其他列表筛选器：

bash

boxyard list --include-group GROUP
boxyard list --exclude-group GROUP
boxyard list --children-of BOX
boxyard list --descendants-of BOX
boxyard list --parent-of BOX
boxyard list --ancestors-of BOX
boxyard list --roots
boxyard list --leaves

Box selection options

Box选择选项

Many commands accept one of:

bash

--box INDEX_NAME       # full <box_id>__<name>
--box-id BOX_ID        # <timestamp>_<subid>
--box-name NAME        # defaults to contains matching for many commands

Name matching options:

bash

--name-match-mode exact|contains|subsequence
--name-match-case
--pick-first           # available on `path`; use only when ambiguity is acceptable

If no box is provided for some commands, Boxyard may infer it from the current working directory when inside

<user_boxes_path>/<index_name>/...

许多命令接受以下参数之一：

bash

--box INDEX_NAME       # 完整的<box_id>__<name>
--box-id BOX_ID        # <timestamp>_<subid>
--box-name NAME        # 多数命令默认包含匹配

名称匹配选项：

bash

--name-match-mode exact|contains|subsequence
--name-match-case
--pick-first           # `path`命令可用；仅当不存在歧义时使用

若部分命令未指定box，当当前工作目录位于

<user_boxes_path>/<index_name>/...

时，Boxyard可能会从当前目录推断对应的box。

Creating boxes

创建boxes

Create an empty box:

bash

boxyard new --box-name NAME

Create from an existing folder, moving the folder into Boxyard:

bash

boxyard new --from /path/to/folder

Copy from an existing folder instead of moving it:

bash

boxyard new --from /path/to/folder --copy

Clone a git repo as a new box:

bash

boxyard new --git-clone git@github.com:user/repo.git

Useful options:

bash

boxyard new --box-name NAME --storage-location STORAGE
boxyard new --box-name NAME --group GROUP --group OTHER_GROUP
boxyard new --box-name NAME --parent PARENT_BOX
boxyard new --box-name NAME --no-initialise-git

创建空box：

bash

boxyard new --box-name NAME

从现有文件夹创建，将文件夹移动到Boxyard中：

bash

boxyard new --from /path/to/folder

从现有文件夹复制而非移动：

bash

boxyard new --from /path/to/folder --copy

克隆Git仓库作为新box：

bash

boxyard new --git-clone git@github.com:user/repo.git

实用选项：

bash

boxyard new --box-name NAME --storage-location STORAGE
boxyard new --box-name NAME --group GROUP --group OTHER_GROUP
boxyard new --box-name NAME --parent PARENT_BOX
boxyard new --box-name NAME --no-initialise-git

Syncing

同步操作

Sync one box:

bash

boxyard sync --box-name NAME
boxyard sync --box INDEX_NAME
boxyard sync --box-id BOX_ID

Sync only selected parts:

bash

boxyard sync --box-name NAME --sync-choices meta
boxyard sync --box-name NAME --sync-choices conf
boxyard sync --box-name NAME --sync-choices data

Sync settings and direction:

bash

boxyard sync --box-name NAME --sync-setting careful
boxyard sync --box-name NAME --sync-setting replace
boxyard sync --box-name NAME --sync-setting force
boxyard sync --box-name NAME --sync-direction push
boxyard sync --box-name NAME --sync-direction pull

Other sync commands:

bash

boxyard multi-sync
boxyard multi-sync --storage-location STORAGE --max-concurrent 3
boxyard multi-sync --box INDEX_NAME --box OTHER_INDEX_NAME
boxyard sync-missing-meta
boxyard box-status --box-name NAME
boxyard yard-status

Soft interruption is enabled by default for long operations: interrupt once or twice to stop after the current operation; repeated interrupts exit immediately.

同步单个box：

bash

boxyard sync --box-name NAME
boxyard sync --box INDEX_NAME
boxyard sync --box-id BOX_ID

仅同步指定部分：

bash

boxyard sync --box-name NAME --sync-choices meta
boxyard sync --box-name NAME --sync-choices conf
boxyard sync --box-name NAME --sync-choices data

同步设置与方向：

bash

boxyard sync --box-name NAME --sync-setting careful
boxyard sync --box-name NAME --sync-setting replace
boxyard sync --box-name NAME --sync-setting force
boxyard sync --box-name NAME --sync-direction push
boxyard sync --box-name NAME --sync-direction pull

其他同步命令：

bash

boxyard multi-sync
boxyard multi-sync --storage-location STORAGE --max-concurrent 3
boxyard multi-sync --box INDEX_NAME --box OTHER_INDEX_NAME
boxyard sync-missing-meta
boxyard box-status --box-name NAME
boxyard yard-status

长时操作默认启用软中断：中断一到两次会在当前操作完成后停止；多次中断会立即退出。

Include, exclude, copy

包含、排除、复制

Include an excluded remote box locally:

bash

boxyard include --box-name NAME
boxyard include --interactive

Exclude a local copy while keeping the remote:

bash

boxyard exclude --box-name NAME
boxyard exclude --interactive --show-sizes
boxyard exclude --box-name NAME --skip-sync

Copy a remote box to an arbitrary destination without adding it to Boxyard tracking:

bash

boxyard copy --box-name NAME --dest ./NAME-copy
boxyard copy --box-name NAME --dest ./NAME-copy --meta --conf
boxyard copy --box-name NAME --dest ./NAME-copy --overwrite

在本地包含已排除的远程box：

bash

boxyard include --box-name NAME
boxyard include --interactive

排除本地副本但保留远程数据：

bash

boxyard exclude --box-name NAME
boxyard exclude --interactive --show-sizes
boxyard exclude --box-name NAME --skip-sync

将远程box复制到任意目标位置，不添加到Boxyard的跟踪列表：

bash

boxyard copy --box-name NAME --dest ./NAME-copy
boxyard copy --box-name NAME --dest ./NAME-copy --meta --conf
boxyard copy --box-name NAME --dest ./NAME-copy --overwrite

Groups and hierarchy

组与层级结构

Groups:

bash

boxyard add-to-group --box-name NAME GROUP [OTHER_GROUP ...]
boxyard remove-from-group --box-name NAME GROUP [OTHER_GROUP ...]
boxyard list-groups --box-name NAME
boxyard list-groups --all --include-virtual
boxyard create-user-symlinks

Parent-child hierarchy:

bash

boxyard add-parent --box-name CHILD --parent-name PARENT
boxyard remove-parent --box-name CHILD --parent-name PARENT
boxyard tree --show-status
boxyard list --view tree --show-status

组操作：

bash

boxyard add-to-group --box-name NAME GROUP [OTHER_GROUP ...]
boxyard remove-from-group --box-name NAME GROUP [OTHER_GROUP ...]
boxyard list-groups --box-name NAME
boxyard list-groups --all --include-virtual
boxyard create-user-symlinks

父子层级操作：

bash

boxyard add-parent --box-name CHILD --parent-name PARENT
boxyard remove-parent --box-name CHILD --parent-name PARENT
boxyard tree --show-status
boxyard list --view tree --show-status

Rename, delete, and force operations

重命名、删除与强制操作

Rename:

bash

boxyard rename --box-name OLD --new-name NEW --scope both
boxyard rename --box-name OLD --new-name NEW --scope local
boxyard rename --box-name OLD --new-name NEW --scope remote

Sync only the name between local and remote:

bash

boxyard sync-name --box-name NAME --to-local
boxyard sync-name --box-name NAME --to-remote

Delete:

bash

boxyard delete --box-name NAME
boxyard delete --box-name NAME --force   # needed when the box has children

Destructive force push:

bash

boxyard force-push --box-name NAME --source /path/to/source --force

重命名：

bash

boxyard rename --box-name OLD --new-name NEW --scope both
boxyard rename --box-name OLD --new-name NEW --scope local
boxyard rename --box-name OLD --new-name NEW --scope remote

仅同步本地与远程之间的名称：

bash

boxyard sync-name --box-name NAME --to-local
boxyard sync-name --box-name NAME --to-remote

删除：

bash

boxyard delete --box-name NAME
boxyard delete --box-name NAME --force   # 当box包含子box时需要此参数

破坏性强制推送：

bash

boxyard force-push --box-name NAME --source /path/to/source --force

Per-box sync configuration

单个box的同步配置

Each box can have a

conf/

folder. Boxyard syncs

conf/

before

data/

, so filters travel with the box.

Special files:

text

conf/.rclone_include  # only sync matching files
conf/.rclone_exclude  # exclude matching files
conf/.rclone_filters  # combined rclone filter rules

conf/.rclone_exclude

is absent, Boxyard uses:

text

~/.config/boxyard/default.rclone_exclude

Default excludes include

.venv/

.pixi/

.trunk/

node_modules/

__pycache__/

, and

.DS_Store

每个box可拥有一个

conf/

文件夹。Boxyard会先同步

conf/

再同步

data/

，因此筛选规则会随box同步。

特殊文件：

text

conf/.rclone_include  # 仅同步匹配的文件
conf/.rclone_exclude  # 排除匹配的文件
conf/.rclone_filters  # 组合的rclone筛选规则

若不存在

conf/.rclone_exclude

，Boxyard会使用：

text

~/.config/boxyard/default.rclone_exclude

默认排除的内容包括

.venv/

、

.pixi/

、

.trunk/

、

node_modules/

、

__pycache__/

以及

.DS_Store

。

Shell helper

Shell辅助工具

The repo includes a zsh helper:

bash

source /path/to/boxyard/shell/boxyard.zsh

Default keybinding:

Ctrl+G

(

BOXYARD_WIDGET_KEY

can override it). Type a partial box name, press the keybinding, and it replaces the current word with a relative path to the selected box. It uses

boxyard-shell-helper search

and

fzf

for multiple matches.

Direct helper examples:

bash

boxyard-shell-helper search TERM
boxyard-shell-helper search TERM --group GROUP
boxyard-shell-helper search TERM --included
boxyard-shell-helper search TERM --excluded

代码库包含一个zsh辅助工具：

bash

source /path/to/boxyard/shell/boxyard.zsh

默认快捷键：

Ctrl+G

（可通过

BOXYARD_WIDGET_KEY

修改）。输入部分box名称，按下快捷键，当前输入的内容会替换为所选box的相对路径。它使用

boxyard-shell-helper search

和

fzf

处理多个匹配结果。

直接使用辅助工具的示例：

bash

boxyard-shell-helper search TERM
boxyard-shell-helper search TERM --group GROUP
boxyard-shell-helper search TERM --included
boxyard-shell-helper search TERM --excluded

Reference files in this repository

本代码库中的参考文件

From this skill directory, the repository root is

../..

Read these for more context when needed:

```
../../README.md
```
— high-level usage and directory layout
```
../../src/boxyard/const.py
```
— default paths and constants
```
../../src/boxyard/config.py
```
— config model and derived paths
```
../../src/boxyard/_cli/main.py
```
— command definitions

../../src/boxyard/_cli/multi_sync.py

—

multi-sync

```
../../src/boxyard/_models.py
```
— box path and metadata layout
```
../../src/boxyard/_shell_helper.py
```
— shell helper behavior

../..

。

如需更多上下文，可阅读以下文件：

```
../../README.md
```
— 高级用法与目录布局
```
../../src/boxyard/const.py
```
— 默认路径与常量
```
../../src/boxyard/config.py
```
— 配置模型与衍生路径
```
../../src/boxyard/_cli/main.py
```
— 命令定义

../../src/boxyard/_cli/multi_sync.py

—

multi-sync

命令实现

```
../../src/boxyard/_models.py
```
— box路径与元数据布局
```
../../src/boxyard/_shell_helper.py
```
— Shell辅助工具行为逻辑