boxyard-cli

Boxyard CLI

Use this skill to use, not develop, Boxyard: managed folders with DATA, metadata, sync config, groups, and local/rclone storage. All bundled paths below resolve from this skill directory; no source checkout is required.

Authority and safety

• Ask before modifying local or remote state. This includes init, new, sync, multi-sync, sync-missing-meta, include, exclude, relocate, delete, rename, sync-name, group/parent edits, create-user-symlinks, copy, force-push, claim, release, discard-local, and non-dry-run convert. Examples are not authorization. Read-only queries, --help, doctor, and convert --dry-run may run without confirmation.
• Never create ad-hoc folders/clones/worktrees in ~/dev. Find the existing box or use boxyard new with approval; put non-box scratch outside managed roots. Keep generated data, even large outputs, inside its related box. Use sync excludes, not sibling folders, to avoid uploading it.
• Resolve identity and placement, don't guess. Both timestamp format and subid length are configurable; index_name is {box_id}__{name}. Use which/path: DATA may be in any checkout root, not just user_boxes_path (default). An unavailable root never falls back to default. Placement is machine-local, never synced in boxmeta.toml; remote storage and local placement are independent.
• Resolve ownership, never bypass it. DATA/CONF pushes compare write_owner with configured machine_name, never a hostname. No owner means unrestricted. new claims by default (--no-claim for work elsewhere); include --read-only suppresses the claim nudge. Refusal also protects force-push, remote/both rename, and deletion. With approval, claim --steal keeps this machine's work; discard-local replaces it from remote and keeps overwritten work in backups.
• Destructive traps: new --from PATH MOVES unless --copy; exclude syncs first then removes local DATA (--skip-sync skips that protection). delete tombstones the id fleet-wide: never delete a stale duplicate name to clean registrations. sync --sync-setting replace|force, copy --overwrite, and force-push --force can overwrite data. Read the relevant reference first.
• Backups aren't garbage: orphan findings may be intentional discard-local keepsakes. Never auto-delete them or infer disposability from unclaimed ULIDs.
• Excludes replace, not extend. A box's conf/.rclone_exclude replaces the default list entirely: copy the default contents before adding rules, or risk syncing .venv/, node_modules/, etc. .rclone_include and .rclone_filters are currently refused; use .rclone_exclude alone. CONF syncs before DATA. Default-exclude edits invalidate DATA baselines fleet-wide; batch needed edits.
• Conversion is explicit: policy edits never reformat existing boxes; only convert does, verifying a byte-identical restore before removing the old copy. Read the storage reference and ~/.config/myagent/reference/box-storage.md before recommending/changing plain vs restic. Rig default is plain; package default for rclone is restic (local is plain). Every participating machine needs Boxyard >=0.7.0, restic and the password before using restic boxes.