boxyard-cli

Boxyard CLI

DATA、メタデータ、同期設定、グループ、およびローカル／rclone ストレージを備えた管理フォルダーで Boxyard を使用するためのスキルです。開発には使用しません。以下のすべてのバンドル済みパスはこのスキルのディレクトリを基準に解決されるため、ソースのチェックアウトは不要です。

権限と安全性

• ローカルまたはリモートの状態を変更する前に確認してください。 これには 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 に場当たり的なフォルダー／クローン／ワークツリーを作成しないでください。 既存のボックスを探すか、承認を得て boxyard new を使用してください。ボックス管理対象ルートの外に、ボックス以外の作業用ファイルを置いてください。 生成データは、大容量であっても、関連するボックス内に保管してください。アップロードを避けるには、兄弟フォルダーではなく同期除外を使用してください。
• 推測せずに、識別情報と配置を確認してください。 タイムスタンプの形式と 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 から処分可能だと判断したりしないでください。
• 除外設定は置き換えであり、追加ではありません。 ボックスの conf/.rclone_exclude はデフォルトリスト全体を置き換えます。ルールを追加する前にデフォルトの内容をコピーしてください。そうしないと、.venv/、node_modules/ などが同期されるおそれがあります。.rclone_include と .rclone_filters は現在拒否されます。.rclone_exclude のみを使用してください。CONF は DATA より先に同期されます。 デフォルト除外設定の編集は、フリート全体の DATA ベースラインを無効にします。必要な編集はまとめて行ってください。
• 変換は明示的に行います： ポリシーの編集では既存のボックスは再フォーマットされません。再フォーマットを行うのは convert のみで、古いコピーを削除する前にバイト単位で同一の復元を検証します。plain と restic のどちらを推奨／変更する場合も、先にストレージリファレンスと ~/.config/myagent/reference/box-storage.md を読んでください。Rig のデフォルトは plain、rclone のパッケージのデフォルトは restic です（ローカルは plain）。restic ボックスを使用する前に、参加するすべてのマシンで Boxyard >=0.7.0、restic、およびパスワードが必要です。

検出、選択、検査

インストール済みの CLI を信頼できる情報源として使用してください：boxyard --help、boxyard <command> --help、boxyard --version。Boxyard の開発チェックアウトで作業している場合は、uv run boxyard ... を優先してください。ソースを探すために、インストール済みスキルを基準に相対移動しないでください。デフォルト以外の設定を使う場合は、boxyard --config /path/to/config.toml ... を使用してください。BOXYARD_CONFIG_PATH はシェルヘルパー用であり、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 は、曖昧さを許容できる場合にのみ使用してください。選択子を指定しない場合は、設定済みルート全体からカレントディレクトリのボックスを選択し、その後 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 を含め、要求されたすべての部分と依存関係を網羅する必要があります。状態が不明、または証明されていないボックスも、実際の同期処理を実行します。移動、破壊的な復旧、変換、一括操作を行う前に、該当するリファレンスとコマンドのヘルプを読んでください。

タスクとリファレンスの対応（必要なものだけ読み込む）

タスク	同梱リファレンス
設定キー、ローカル／リモートのレイアウト、ルート、選択子、フィルター、標準的な検出方法	検出とパス
新規作成／包含／除外／コピー、移動、グループ／階層、名前変更／削除／強制実行	ボックスのライフサイクル
同期モード、multi-sync の証明、実行間隔、plain／restic の変換、除外	同期とストレージ
所有権／claim／release／discard-local、doctor の検出結果／復旧ヒント	所有権と健全性
Ctrl+G、fzf、ヘルパー検索、zsh の設定	シェルヘルパー

パッケージのデフォルトパスは rig のパスとは異なります。実際の設定（通常は ~/.config/boxyard/config.toml）を読み、path を使用してください。リファレンスには詳細な例と根拠が記載されています。過去の件数は、現在の環境全体の一覧ではありません。