@pixlcore/xycli 1.0.7 → 1.0.9

package/README.md

@@ -134,7 +134,7 @@ These switches control output or execution across many commands. Add them to the
 | Switch | Short form | What it does |
 | --- | --- | --- |
 | `--verbose` | `-v` | Show extra detail. Resource views may expand scripts, parameters, or monitoring sections; many mutation commands also display API requests and responses. |
-| `--quiet` | `-q` | Suppress ordinary terminal output and progress displays. JSON data still prints, and fatal error messages remain visible on stderr. |
+| `--quiet` | `-q` | Suppress ordinary terminal output and progress displays. JSON data still prints, and human-readable warnings and errors remain visible on stderr. |
 | `--dry` | | Preview a supported operation without applying it. Resource mutations, imports, exports, sync, and API calls use this to show planned changes or requests. It does not prevent connection checks or reads, and does not apply to local `xy config` updates. |
 | `--format json` | `-f json` | Display supported results as indented JSON instead of the usual report or table. |
 | `--format jsonc` | `-f jsonc` | Display supported results as compact JSON on one line. Here, `jsonc` means compact JSON. |
@@ -157,7 +157,7 @@ XYOPS_COLOR=false xy events --format json --quiet > ./events.json
 xy categories -f jsonc -q > ./categories.json
 ```
 
-Fatal errors print to stderr and exit with a nonzero status even in quiet mode, so redirecting JSON output to a file leaves those errors visible in your terminal. Quiet mode can still suppress command-specific warnings and failure reports, such as sync messages or import results. Sync warnings and errors still produce a nonzero exit status. Check exit status and any structured results when scripting; omit `--quiet` when you need those detailed diagnostics.
+Human-readable warnings and errors print to stderr even in quiet mode, so redirecting JSON output to a file leaves those diagnostics visible in your terminal. Structured JSON results may also include warnings and errors. Sync warnings and errors still produce a nonzero exit status. Check exit status and any structured results when scripting.
 
 JSON output varies by command: some local collection views return all matches even when their table view is paginated, while database searches may return only the selected page. Some commands print multiple JSON values, such as the request and response from `xy api`. Check the command reference when using the output in a script.
 

package/docs/help.md

@@ -200,6 +200,8 @@ xy sync ./ --down events,plugins
 xy sync ./ --up categories,plugins --down events --dry
 xy sync ./ --up events --down events --dry
 xy sync ./ --up all --dry
+xy sync ./ --up buckets --dry
+xy sync ./ --down buckets
 xy sync --up events,plugins --verbose
 ```
 
@@ -211,8 +213,9 @@ Pass one or more base directories, or omit them to scan the current directory. F
 - `--down TYPES` updates local files from xyOps.
 - `--dry` previews changes without applying them.
 - `--verbose` shows full diffs and API requests and responses.
+- `--ignore_missing` skips local sources whose type and ID are absent from xyOps, without a warning or failure. It leaves their files untouched.
 
-You must enable at least one direction. `TYPES` is a comma-separated list of `alerts`, `api_keys`, `categories`, `channels`, `events`, `groups`, `monitors`, `plugins`, `tags`, or `web_hooks`. Use `all` to select every supported type. Workflows are included under `events`. Buckets, Secrets, Users, and Roles are not supported.
+You must enable at least one direction. `TYPES` is a comma-separated list of `alerts`, `api_keys`, `buckets`, `categories`, `channels`, `events`, `groups`, `monitors`, `plugins`, `tags`, or `web_hooks`. Use `all` to select every supported type. Workflows are included under `events`. Bucket sync requires xyOps v1.1.2 or later. Secrets, Users, and Roles are not supported.
 
 Enable both directions for the same type to use experimental two-way sync. The newest modification time wins, including external property files. Git checkouts can reset filesystem timestamps, so prefer one-way sync when reliable conflict handling matters. Dry runs never update xyOps, write files, run completion commands, or send notifications.
 
@@ -222,6 +225,8 @@ Repeated sources with the same type and ID generate warnings, even if their cont
 
 External string properties are loaded automatically from adjacent files named `BASENAME-PROPERTY.EXT`, such as `My-Plugin-script.js` beside `My-Plugin.json`, or `My-Event-params.script.sh` beside `My-Event.json`. The extension is your choice. Keep only one external file per property, and rename its basename along with the JSON file.
 
+Bucket metadata uses a normal XYPDF source. For a Bucket titled `My Bucket Name`, its separate JSON data and uploaded files live beside `buckets/My-Bucket-Name.json` in `buckets/My-Bucket-Name/data.json` and `buckets/My-Bucket-Name/files/`. Both `data.json` and `files/` are required for a selected local bucket. Bucket data upsync replaces the entire remote data object. Bucket files are matched by xyOps filename normalization and transferred according to size and modification time. Two-way bucket sync uses the data record and file timestamps from xyOps; a transfer updates local file times to match. Bucket files missing locally are deleted remotely only with up-only `--delete buckets`.
+
 **Delete mode**
 
 Add `--delete TYPES` to delete xyOps objects that have no matching source in the scanned directories. Deletion requires up-only sync and a complete local inventory. The CLI rejects deletion if upsync is disabled or any downsync direction is enabled, including saved defaults and dry runs. Use `--down false` to disable inherited downsync. See [Delete mode](sync.md#delete-mode) before using it.
@@ -235,6 +240,16 @@ xy sync ./ --up events,plugins --delete events
 
 **The scanned directories must contain a complete inventory of the other objects you intend to keep for every type selected for deletion.** Delete mode is not limited to previously synced objects. A missing file, incomplete export, or unavailable mount can cause unintended deletions of your own definitions. Verify that all source directories are available and inspect a dry run before removing `--dry`. Source warnings or scan errors stop the run before any updates begin. If an update or sync-tracking API operation fails, earlier successful updates remain in place, but the entire delete pass is skipped for that run.
 
+**System Hook deletions**
+
+Use `--syshook ACTION` when a matching xyOps System Hook launches the CLI. This supports deletion hooks for every standard sync definition type except Buckets. It reads the activity JSON from STDIN and removes only the XYPDF with the matching type and ID, plus its neighboring property files. It does not run ordinary sync, compare definitions, or call the xyOps API. Pass exactly one sync directory, and use an absolute path because System Hooks start in a temporary directory. See the [supported actions](sync.md#system-hook-deletion) for the exact hook names, including `apikey_delete` for API Keys.
+
+```sh
+xy sync /srv/xyops-automation --syshook event_delete --down_cmd /usr/local/sbin/commit-xyops-deletion
+```
+
+`--down_cmd` runs from the sync directory only after files are actually removed. A missing local source is a successful no-op; duplicate matching sources stop the command without deleting either one. `--dry` previews the files without deleting them or running `down_cmd`. No xyOps URL or API Key is needed. See [System Hook deletion](sync.md#system-hook-deletion) for configuration and operational details.
+
 **Completion commands and notifications**
 
 ```sh
@@ -250,7 +265,7 @@ xy sync ./ --up events,plugins \
 - `--error_email ADDRESS` sends warnings and errors by email through xyOps.
 - `--error_event EVENT_ID` runs an Event on warnings or errors.
 
-Completion commands run in a local shell in the first base directory. Deletions alone do not trigger them. Event notifications receive `input.data.errors` and `input.data.warnings`.
+Completion commands run in a local shell in the first base directory. Successful up-only deletion triggers `up_cmd`; local System Hook deletion triggers an explicitly supplied `down_cmd`. Event notifications receive `input.data.errors` and `input.data.warnings`.
 
 The configured API Key needs the appropriate resource permissions and `update_state` for sync tracking updates. Notification actions also need their usual permissions. Earlier successful changes are not rolled back if a later operation fails. Retry the sync after correcting an error; previously applied updates compare equal, and deletion remains disabled until the pre-delete phase completes without warnings or errors.
 
@@ -282,6 +297,7 @@ Export existing xyOps definitions into a starter sync tree in the current direct
 
 ```sh
 xy sync setup events plugins categories --dry
+xy sync setup buckets
 xy sync setup events plugins categories --file_props script,params.script
 xy sync setup events --file_props params.script --default_ext ps1
 xy sync setup events plugins --new
@@ -296,9 +312,12 @@ Choose one or more resource types separated by spaces, or use `all`. Supported t
 
 Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Events and workflows are grouped into subfolders using their Category title as a slug. Both are synced with `--up events` or `--down events`. Setup stops before writing if an Event or workflow selected for export refers to a missing Category.
 
+For each Bucket, setup also writes `BUCKET-SLUG/data.json` and downloads its files into `BUCKET-SLUG/files/` beside the XYPDF file. `--new` skips Bucket definitions already present locally, including their content. `--force` permits overwriting existing Bucket content files.
+
 - `--file_props PATHS` extracts string properties into adjacent files.
 - `--default_ext EXT` sets the fallback neighbor extension instead of `txt`.
 - `--new` writes only remote definitions not already represented locally.
+- `--ignore_missing` lets `--new` skip local sources whose type and ID are absent from xyOps.
 - `--down_cmd COMMAND` runs after setup writes one or more definitions.
 - `--cmd_timeout SECONDS` changes the command timeout from 30 seconds.
 - `--stock` includes stock objects, which are omitted by default.
@@ -310,7 +329,7 @@ For `--file_props`, use comma-separated property names or dot paths, such as `sc
 
 The same property selection also checks every workflow node automatically. For example, `params.script` in a node's `data` becomes a neighbor such as `My-Workflow-workflow.nt3sr3y4.params.script.sh`. The node ID in the filename identifies which node owns the property. No additional setup option is needed.
 
-Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
+Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. With `--ignore_missing`, only sources whose type and ID are absent from xyOps are skipped. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
 
 An explicitly supplied `--down_cmd` runs from the current setup directory after at least one definition is written. It does not run when `--new` finds nothing or during a dry run. Saved sync completion commands are not inherited by setup.
 

package/docs/sync.md

@@ -54,6 +54,7 @@ Use these names with `--up`, `--down`, `--delete`, and setup:
 | --- | --- |
 | `alerts` | Alert definitions, rather than their invocations. |
 | `api_keys` | API Key definitions. |
+| `buckets` | Bucket definitions, JSON data, and uploaded files. Requires xyOps 1.1.2 or later. |
 | `categories` | Event Categories. |
 | `channels` | Notification Channels. |
 | `events` | Events and workflows. |
@@ -65,7 +66,7 @@ Use these names with `--up`, `--down`, `--delete`, and setup:
 
 `all` selects every supported type. Supply multiple types as a comma-separated string without spaces, such as `events,plugins,categories`.
 
-Buckets, Secret Vaults, Users, and Roles are not supported by sync. Individual workers, jobs, Tickets, Alert history, and snapshots are also outside its definition-sync scope. Workflows use the `events` selection even though setup places them in a separate folder (for convenience).
+Secret Vaults, Users, and Roles are not supported by sync. Individual workers, jobs, Tickets, Alert history, and snapshots are also outside its definition-sync scope. Workflows use the `events` selection even though setup places them in a separate folder (for convenience).
 
 ### Permissions
 
@@ -127,6 +128,8 @@ xyops-automation/
 
 Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`, then grouped into subfolders using their Category titles. Both participate in normal sync through the `events` selection.
 
+Bucket setup also creates a sibling directory for each Bucket's content. For example, a Bucket titled `My Bucket Name` has `buckets/My-Bucket-Name.json`, `buckets/My-Bucket-Name/data.json`, and `buckets/My-Bucket-Name/files/` for its definition, data, and uploaded files. Move or rename the sibling directory with the XYPDF file. A normal Bucket sync requires both the data file and files directory, even when they contain an empty object and no files. Bucket data upsync replaces the full remote data object, including removed keys. File transfers match xyOps normalized filenames and align local modification times with the server's timestamps after each transfer.
+
 Folder and filenames come from Category and definition titles: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, the Event `Nightly Backup` in the `Operations` Category becomes `events/Operations/Nightly-Backup.json`. Different titles can produce the same path, so review the preview for collisions. Setup stops before writing anything if an Event or workflow selected for export refers to a Category that is not present in xyOps.
 
 ### 4. Review and version the tree
@@ -169,7 +172,7 @@ xy sync setup events plugins categories --new --file_props script,params.script
 xy sync setup events plugins categories --new --file_props script,params.script
 ```
 
-New-only setup scans the current directory recursively and indexes existing XYPDF sources by item type and exact ID. Renamed files and custom folders are preserved. Remote definitions not found in that index are written to setup's normal type and Category folders; existing definitions are skipped without being rewritten. Malformed, duplicate, unsupported, or locally orphaned sources stop the operation before new files are written. `--new` cannot be combined with `--force`.
+New-only setup scans the current directory recursively and indexes existing XYPDF sources by item type and exact ID. Renamed files and custom folders are preserved. Remote definitions not found in that index are written to setup's normal type and Category folders; existing definitions are skipped without being rewritten. Malformed, duplicate, unsupported, or locally orphaned sources stop the operation before new files are written. Add `--ignore_missing` to skip only local sources whose type and ID are absent from xyOps. `--new` cannot be combined with `--force`.
 
 This is an additive local export. It does not create definitions in xyOps, and ordinary upsync or downsync still updates only definitions that already exist on both sides.
 
@@ -391,15 +394,17 @@ Relative paths resolve against the CLI's current working directory. Completion c
 | `--up TYPES` | `sync.up` | Disabled | Sync upwards to xyOps from local sources for these types. |
 | `--down TYPES` | `sync.down` | Disabled | Down downwards to existing local sources from xyOps for these types. |
 | `--delete TYPES` | `sync.delete` | Disabled | Delete remote objects with no local source. Use only in an up-only workflow; see [Delete mode](#delete-mode). |
+| `--syshook ACTION` | n/a | Disabled | Handle one supported definition deletion activity from STDIN as a local-only deletion; see [System Hook deletion](#system-hook-deletion). |
+| `--ignore_missing` | `sync.ignore_missing` | Off | Skip local sources whose type and ID are absent from xyOps, without a warning or failure. Leave their files untouched. |
 | `--up_cmd COMMAND` | `sync.up_cmd` | None | Run a local shell command after at least one successful upsync. |
-| `--down_cmd COMMAND` | `sync.down_cmd` | None | Run a local shell command after at least one successful downsync. |
+| `--down_cmd COMMAND` | `sync.down_cmd` | None | Run a local shell command after at least one successful downsync, or an explicit command after a System Hook deletion. |
 | `--cmd_timeout SECONDS` | `sync.cmd_timeout` | `30` | Timeout for each completion command. |
 | `--error_email ADDRESS` | `sync.error_email` | None | Email collected warnings and errors through xyOps. |
 | `--error_event EVENT_ID` | `sync.error_event` | None | Launch an Event with collected warnings and errors in its input data. |
 | `--lock_file PATH` | `sync.lock_file` | Temporary file keyed by `base_url` | Use an explicit path for the built-in PID lock. |
 | `--dry` | n/a | Off | Dry-Run Mode: Preview without writes, completion commands, or notifications. |
 | `--verbose`, `-v` | n/a | Off | Show complete diffs and additional request, response, and write details. |
-| `--quiet`, `-q` | n/a | Off | Suppress routine output and progress. Fatal errors remain visible, but collected sync warnings and errors can be suppressed. |
+| `--quiet`, `-q` | n/a | Off | Suppress routine output and progress. Warnings and errors remain visible on standard error. |
 
 At least one direction must be enabled. The command is a single run, not a background watcher; repeat it through a scheduler or hook for automatic operation.
 
@@ -414,6 +419,7 @@ At least one direction must be enabled. The command is a single run, not a backg
 | `--file_props PATHS` | Extract string properties into adjacent neighbor files. Accepts comma-separated dot paths or a JSON array. |
 | `--default_ext EXT` | Use this extension instead of `txt` when a neighbor's type cannot be detected. A leading dot is optional. |
 | `--new` | Export only remote definitions whose type and ID are not already present in the current local tree. |
+| `--ignore_missing` | With `--new`, skip local sources whose type and ID are absent from xyOps. Leave their files untouched. |
 | `--down_cmd COMMAND` | Run a local shell command after setup writes one or more definitions. |
 | `--cmd_timeout SECONDS` | Set the setup completion-command timeout in seconds. The default is `30`. |
 | `--stock` | Include stock definitions that ships wit xyOps (e.g. "Shell Plugin"), which setup normally omits. |
@@ -439,7 +445,61 @@ For each differing definition, the engine compares xyOps's `modified` timestamp
 
 Two-way sync is experimental. Keep clocks synchronized, review dry runs, and preserve a history of both configuration and scripts. Git checkout, clone, restore, or file copying can give old content a new filesystem timestamp.
 
-For automatic two-way operation, use a persistent tree and run every minute. Both directions are considered on each run; you do not need separate alternating up and down jobs. Newly created definitions still need a setup export or individual local source, and remotely deleted definitions leave their old source files behind until you remove them.
+Bucket data and files use their own modification times, separate from the Bucket definition. When contents differ, two-way sync compares `data.json` with the data record's modification time and each local file with the matching manifest date. Equal timestamps with differing Bucket content are reported as conflicts. After a transfer, xyCLI sets the local modification time to the server's returned time.
+
+Bucket file comparison uses size and modification time because the manifest has no content hash. A same-size change with an unchanged timestamp cannot be detected.
+
+For automatic two-way operation, use a persistent tree and run every minute. Both directions are considered on each run; you do not need separate alternating up and down jobs. Newly created definitions still need a setup export or individual local source.
+
+### Remove a definition during two-way sync
+
+Two-way sync does not propagate deletions. Definition deletions are usually infrequent, so coordinating them manually is generally practical. Keep `--delete false` in the scheduled command, and remove a definition from both sides deliberately:
+
+1. Delete the definition in the xyOps web interface first.
+2. Remove its local XYPDF JSON file and any neighboring external property files. If the tree is stored in Git, commit and push their removal so the dedicated sync checkout receives the deletion.
+3. Run sync again, or resume the schedule, after the local files are gone. Without `--ignore_missing`, pause the schedule during these steps if you want to avoid a failed pass between the two removals.
+
+If a sync runs after the xyOps deletion but before local cleanup, the leftover source normally produces a missing-object warning and stops the run before any definition changes. Add `--ignore_missing` to ordinary sync and any following `sync setup --new` command to skip that source and keep processing other definitions. This does not remove the local files or propagate the deletion to Git. Remove those files yourself to complete the deletion. Other scan warnings and errors still stop the run.
+
+Do not remove the Git files first while the definition still exists in xyOps. A scheduled `sync setup --new` pass can export the still-existing definition back into the repository. See the [Two-Way Git Sync Tutorial](two-way-git-tutorial.md#delete-a-definition-from-both-sides) for the Git workflow.
+
+### System Hook deletion
+
+xyOps [System Hooks](https://docs.xyops.io/#Docs/syshooks) can launch xyCLI when a standard synced definition is deleted. Configure each deletion action you need separately. The `--syshook` command reads the activity JSON from STDIN, checks that its action matches the command, and uses the deleted object's type and exact ID to find one local XYPDF source. It removes that source and its neighboring external property files. Other local definitions, including new ones not yet in xyOps, are left alone.
+
+| Sync selection | System Hook action |
+| --- | --- |
+| `alerts` | `alert_delete` |
+| `api_keys` | `apikey_delete` |
+| `categories` | `category_delete` |
+| `channels` | `channel_delete` |
+| `events` (including workflows) | `event_delete` |
+| `groups` | `group_delete` |
+| `monitors` | `monitor_delete` |
+| `plugins` | `plugin_delete` |
+| `tags` | `tag_delete` |
+| `web_hooks` | `web_hook_delete` |
+
+Buckets are excluded because a Bucket may have separate JSON data and uploaded files alongside its XYPDF source. The `bucket_delete` activity is not supported by `--syshook`.
+
+For example, configure the following hooks on the primary conductor, adjusting executable and checkout paths:
+
+```json
+{
+	"hooks": {
+		"event_delete": {
+			"shell_exec": "/usr/local/bin/xy sync /srv/xyops-automation --syshook event_delete --down_cmd /usr/local/sbin/commit-xyops-deletion"
+		},
+		"plugin_delete": {
+			"shell_exec": "/usr/local/bin/xy sync /srv/xyops-automation --syshook plugin_delete --down_cmd /usr/local/sbin/commit-xyops-deletion"
+		}
+	}
+}
+```
+
+The `--down_cmd` script can stage, commit, and push the deletions in a dedicated Git checkout. It runs only after at least one file was removed. A missing source is a successful no-op, and duplicate matching sources stop the command before any files are removed. Use `--dry` to preview the selected files without changing them or running the completion command.
+
+This mode does not run ordinary sync, fetch remote definitions, or change xyOps. It ignores saved sync direction settings and requires exactly one directory. No xyOps URL or API Key is needed. The CLI still uses a host-local lock, with a fixed default lock key when no `base_url` is configured. System shell hooks run on the primary conductor from a temporary directory, and xyOps limits them to 60 seconds. The conductor must be able to access the checkout and Git credentials. If regular sync runs on another host, its local lock cannot protect this checkout; arrange for both operations to use the same host and lock if they share a checkout. Watch hook failures and Git push failures, because a failed hook is not automatically retried.
 
 ## Remote-management warnings
 
@@ -499,6 +559,8 @@ Deleting an Event does not automatically remove its dependencies. Remote API rul
 
 Deletion only begins after every update has completed and the sync-tracking state has been written without warnings or errors. If either phase fails, the entire delete pass is skipped for that run. Earlier successful updates remain in place, so correct the error and retry; definitions already updated will compare equal. Once deletion begins, successful earlier deletions are not rolled back if a later deletion fails.
 
+With `--delete buckets`, a remote Bucket file missing from a selected local Bucket's `files/` directory is deleted individually. Removing the Bucket XYPDF source deletes the whole Bucket, including all its data and files. A missing or invalid `data.json`, incomplete file inventory, or failed transfer prevents Bucket file deletion and the whole-object delete pass.
+
 An unavailable base directory stops the scan, but an existing empty directory can look like an empty inventory. Do not treat that guard as protection against an empty mount, accidental file removal, or missing exports of your own definitions.
 
 Keep deletion disabled in general-purpose cron, Git hooks, and CI until you have a deliberate policy for maintaining and checking the complete inventory. Disable saved deletion for other runs with `--delete false`.
@@ -523,7 +585,7 @@ xy sync ./ --down events,plugins --down_cmd "./commit-downloads.sh" --cmd_timeou
 ### When commands run
 
 - `up_cmd` runs if at least one object was successfully upsynced (this includes deletes).
-- `down_cmd` runs if at least one object was successfully downsynced.
+- `down_cmd` runs if at least one object was successfully downsynced. In `--syshook` mode, an explicitly supplied `down_cmd` runs after the matching local files are deleted.
 - During setup, an explicitly supplied `down_cmd` runs if at least one definition was written.
 - If both apply, `up_cmd` runs first, then `down_cmd`.
 - Neither runs for an identical/no-op run, a scan that stopped before changes, or a dry run.
@@ -614,7 +676,7 @@ Runs with no warnings or errors exit with status `0`. Scan warnings prevent chan
 
 Every `xy sync` command acquires a host-local PID lock before it loads remote definitions or touches local files. This includes ordinary up, down, two-way, delete, dry-run, and setup operations. The lock remains held through completion commands and error notifications, so every CLI entry point uses the same overlap protection automatically.
 
-By default, xyCLI creates a lock file in the operating system's temporary directory. Its filename contains a hash of the normalized `base_url`, so syncs targeting the same xyOps instance on one host serialize even when they use different directories or API Keys. Syncs for different instances use different default locks.
+By default, xyCLI creates a lock file in the operating system's temporary directory. Its filename contains a hash of the normalized `base_url`, so syncs targeting the same xyOps instance on one host serialize even when they use different directories or API Keys. Syncs for different instances use different default locks. System Hook deletions without a configured `base_url` use a fixed local key instead.
 
 When another live sync process owns the lock, the new command stops before doing any work, prints the owning PID and lock path, and exits nonzero. It does not wait or queue. Schedulers can try again on their next run. If a process was forcibly terminated and left its PID file behind, the next invocation detects that the PID is dead, removes the stale file, atomically acquires a replacement, and continues.
 
@@ -670,7 +732,7 @@ PATH=/usr/local/bin:/usr/bin:/bin
 
 Choose only the item types your tree manages. This example explicitly disables downsync and deletion. Add `--error_event EVENT_ID` if you prefer an error-handling Event, or configure notifications in the account's CLI config file.
 
-`--quiet` keeps routine progress and diffs out of cron's output, avoiding an email for every ordinary run. Fatal CLI errors still print to standard error. Collected sync warnings and errors can be suppressed, so quiet automation should have configured notifications and external monitoring. Remove `--quiet` while investigating a problem.
+`--quiet` keeps routine progress and diffs out of cron's output, avoiding an email for every ordinary run. Warnings and errors still print to standard error. Configure notifications if you also want xyOps to send a message or launch an Event when sync encounters a problem.
 
 If the previous run is still active, the built-in PID lock rejects the overlapping invocation with a nonzero exit status. The next minute tries again. A single sync can therefore take longer than a minute without starting another copy.
 
@@ -925,7 +987,7 @@ Repository concurrency controls these workflow runs. Coordinate all writers to t
 | `down_cmd` does not run | Normal sync requires a successful download. Setup requires at least one written definition and an explicit `--down_cmd`. No-op and dry runs do not trigger it. |
 | A download commit launches another sync | Disable deployment Git hooks for commits made by `down_cmd`. The nested sync will otherwise be rejected by the built-in PID lock. |
 | Sync reports another PID is running | Another local sync owns the lock. Let it finish. If the PID is no longer alive, the next run recovers the stale file automatically. If the PID belongs to an unrelated recycled process, verify that no sync is active before removing the reported lock file. |
-| A scheduled run prints nothing | `--quiet` suppresses routine output and collected reports. Remove it to investigate and configure notifications. |
+| A scheduled run prints nothing | `--quiet` suppresses routine output. Warnings and errors still print to standard error. Check that the scheduler captures it. |
 | Sync exits nonzero after a warning report | Scan warnings prevent changes from being applied, so warnings and errors both exit with status `1`. Resolve the reported problem before retrying. |
 | Notifications never arrive | Check API access, email setup and privileges, the error Event's manual trigger, and failures occurring before reporting. |
 | API Key updates behave differently after import | Portable definitions do not transfer usable secret key material. Treat key credentials separately from their definitions. |

package/docs/two-way-git-tutorial.md

@@ -108,7 +108,7 @@ This considers both directions for every local Event and workflow source:
 - A newer xyOps definition is downloaded to its existing local file.
 - Identical definitions are left alone.
 
-The `--delete false` switch is intentional. Two-way sync does not propagate deletions safely. Delete an item deliberately on both sides, and keep deletion disabled in the scheduled command.
+The `--delete false` switch is intentional. Two-way sync does not propagate deletions. Keep deletion disabled in the scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item.
 
 Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
 
@@ -151,6 +151,7 @@ GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
 	--up events \
 	--down events \
 	--delete false \
+	--ignore_missing \
 	--down_cmd "$GIT_DOWN_CMD" \
 	--cmd_timeout 120
 
@@ -159,6 +160,7 @@ GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
 # The setup completion command runs only when new files were actually written.
 "$XY_BIN" sync setup events \
 	--new \
+	--ignore_missing \
 	--file_props script,params.script \
 	--default_ext ps1 \
 	--down_cmd "$GIT_DOWN_CMD" \
@@ -185,6 +187,8 @@ The two uses of `--down_cmd` are deliberately identical:
 - `sync setup --new` runs it only after at least one new local definition is written.
 - A no-op or dry run does not create a commit or push.
 
+The two `--ignore_missing` switches let the script continue while a definition deleted in xyOps still has a local XYPDF source. Other definitions can sync and new xyOps definitions can be exported during that interval. The stale source and its neighboring files remain in Git until you remove and push them. Other scan problems still stop the run.
+
 The command stages the entire dedicated repository with `git add --all`. Do not use this script in a checkout containing unrelated work. If your repository contains other material, narrow the Git paths in `GIT_DOWN_CMD`.
 
 ## 5. Schedule the script with cron
@@ -207,7 +211,7 @@ Run the script every minute, with `flock` outside the script:
 * * * * * /usr/bin/flock --nonblock --conflict-exit-code 0 /tmp/xyops-git-sync.lock /usr/local/sbin/xyops-git-sync >/dev/null
 ```
 
-Cron normally emails job output when local mail delivery is configured. This entry discards routine standard output so successful runs remain silent, but leaves standard error alone so failures can still trigger mail. The xyCLI commands deliberately omit `--quiet`, because that option can suppress collected sync warnings and error reports along with routine output.
+Cron normally emails job output when local mail delivery is configured. This entry discards routine standard output so successful runs remain silent, but leaves standard error alone so failures can still trigger mail. The xyCLI commands show progress when run manually; you can add `--quiet` to suppress that progress while keeping warnings and errors on standard error.
 
 To keep successful output in a log instead, replace `>/dev/null` with an append redirect to a file that the sync account can write. Do not place that log inside the Git repository because the completion command stages the whole tree.
 
@@ -245,6 +249,18 @@ When someone creates a new Event in xyOps, the ordinary sync pass does not know
 
 `--new` is additive. It does not overwrite existing sources, and it matches existing definitions by type and exact ID rather than filename. This preserves renamed files and custom folder layouts.
 
+### Delete a definition from both sides
+
+You can automate deletions made in xyOps with [System Hook deletion](sync.md#system-hook-deletion). For manual coordination, the `--ignore_missing` switches let the scheduled script keep running while you complete these steps:
+
+1. Delete the definition in the xyOps web interface first.
+2. Remove its XYPDF JSON file and all neighboring property files from Git, then commit and push the deletion.
+3. Check that the dedicated sync checkout receives the commit and completes a later sync run.
+
+If the script runs after the xyOps deletion but before the Git deletion reaches its checkout, both sync commands skip that local source without treating it as a warning. They leave its files in place and continue processing other definitions. Remove and push the stale files to complete the deletion. Without `--ignore_missing` on both commands, the missing source stops the script.
+
+Do not remove the Git files first. While the definition still exists in xyOps, `sync setup --new` can export it again and commit the files back to Git. This is a manual deletion procedure, not automatic two-way deletion. See the [Sync Guide](sync.md#remove-a-definition-during-two-way-sync) for the general behavior.
+
 ## Troubleshooting
 
 | Symptom | What to check |
@@ -255,7 +271,7 @@ When someone creates a new Event in xyOps, the ordinary sync pass does not know
 | The wrong side wins a two-way conflict | Check NTP, the xyOps conductor clock, and the modification times of the JSON and neighboring files. A checkout, restore, or file copy can refresh local timestamps. |
 | A new Event is not exported | Confirm `sync setup events --new` runs from the repository root and that the API Key can see the Event. Add the correct property path if its script is stored somewhere other than `params.script`. |
 | A new Git file is not created in xyOps | Ordinary sync updates definitions that already exist on both sides. Create or import the definition into xyOps first, then let sync manage subsequent changes. |
-| A deleted item reappears or causes an error | Two-way deletion is not supported. Remove the local source and the xyOps definition deliberately as one coordinated operation. |
+| A deleted item reappears or causes an error | Follow the [coordinated deletion steps](#delete-a-definition-from-both-sides): delete in xyOps first, then remove and commit its local files. Use `--ignore_missing` on both sync commands to keep the script running during the gap. |
 | A cron run is skipped | Another cron invocation may hold the `flock` lock. The lock file itself may remain when no lock is held, so check for a running sync process rather than treating the file as stale. |
 | A completion command times out | Increase `--cmd_timeout`, investigate Git network latency, and confirm that Git cannot wait for interactive input. |
 

package/index.js

@@ -18,6 +18,15 @@ if (!process.env.XYOPS_USER_AGENT) {
 	process.env.XYOPS_USER_AGENT = `xyOps CLI v${pkg.version} (Node.js); ${os.hostname()} (${os.platform()}/${os.arch()})`;
 }
 
+// Warnings and errors must reach stderr even in quiet mode. Install this
+// before cli.global() so its global warn() helper is bound to cli as usual.
+cli.warn = function(msg) {
+	if (this.progress.running) this.progress.erase();
+	process.stderr.write(msg);
+	if (this.progress.running) this.progress.draw();
+	this.log(msg);
+};
+
 cli.global();
 
 cli.mapArgs({
@@ -26,7 +35,8 @@ cli.mapArgs({
 	'd': 'debug',
 	'f': 'format',
 	'r': 'raw',
-	'h': 'help'
+	'h': 'help',
+	'ignore-missing': 'ignore_missing'
 });
 
 process.on('SIGINT', function() { cli.progress.end(); process.exit(130); } );
@@ -39,6 +49,14 @@ Uncatch.on('uncaughtException', function(err) {
 	cli.progress.end();
 });
 
+cli.emoji = function(emoji) {
+	// override cli.emoji with our own TTY-aware version (FUTURE: Remove this patch after pixl-cli v1.1.7+)
+	// Draw the emoji, restore its starting cursor position, then explicitly move
+	// forward two cells.  This overrides each terminal's automatic cursor advance.
+	if (!cli.tty()) return emoji;
+	return '\u001b7' + emoji + '\u001b8\u001b[2C';
+};
+
 const { api } = require('@pixlcore/xyops-sdk');
 var highlight = require('cli-highlight').highlight;
 const Tools = cli.Tools;
@@ -232,6 +250,14 @@ const app = {
 		delete args.quiet;
 		delete args.verbose;
 		
+		// A System Hook deletion uses only its STDIN payload and local XYPDF
+		// files.  Run it before the normal xyOps API credential and config fetch.
+		if ((cmd == 'sync') && ('syshook' in args)) {
+			await this.cmd_sync();
+			print("\n");
+			return;
+		}
+		
 		// create temp dir if needed
 		this.tempDir = this.config.temp_dir || Path.join( os.tmpdir(), 'xyops', 'cli' );
 		if (!fs.existsSync(this.tempDir)) Tools.mkdirpSync( this.tempDir );
@@ -357,10 +383,7 @@ const app = {
 		print( "\n " + cyan.bold("Request:") );
 		this.jsonOutput(this.args);
 		
-		if (this.dry) {
-			this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
-			return;
-		}
+		if (this.dry) return;
 		
 		cli.progress.start({ amount: 1, pct: false, text: gray('→ ' + name) });
 		var { err, data } = await this.api[name](this.args);
@@ -408,6 +431,8 @@ const app = {
 	
 	dieUsage(heading) {
 		// print help and exit
+		if (cli.args.quiet) this.die("Invalid usage. Run 'xy help " + heading + "' for details.");
+		
 		this.printHelp(heading);
 		println("");
 		process.exit(1);
@@ -453,6 +478,8 @@ Tools.mergeHashInto( app, require('./lib/webhook.js') );
 Tools.mergeHashInto( app, require('./lib/transfer.js') );
 Tools.mergeHashInto( app, require('./lib/marketplace.js') );
 Tools.mergeHashInto( app, require('./lib/sync.js') );
+Tools.mergeHashInto( app, require('./lib/sync-buckets.js') );
+Tools.mergeHashInto( app, require('./lib/sync-syshook.js') );
 
 global.app = app;
 

package/lib/apikey.js

@@ -241,7 +241,7 @@ module.exports = {
 		println( "\n " + cyan.bold("API Key Secret: ") + bold(data.plain_key) );
 		println( " " + yellow.bold("Save this secret now.  It will never be displayed again.") );
 		if (state_error) {
-			println( "\n " + red.bold("Disable Error: ") + (state_error.message || state_error) );
+			warnln( "\n " + red.bold("Disable Error: ") + (state_error.message || state_error) );
 			process.exitCode = 1;
 			return;
 		}

package/lib/buckets.js

@@ -218,7 +218,6 @@ module.exports = {
 		if (this.dry) {
 			if (files.length) {
 				this.jsonOutput({ files: files });
-				this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
 			}
 			return;
 		}
@@ -475,10 +474,7 @@ module.exports = {
 				output: dest_file
 			});
 		}
-		if (this.dry) {
-			this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
-			return;
-		}
+		if (this.dry) return;
 		
 		println( "\n " + this.color('theme').bold('BUCKET FILE: ' + file.filename) );
 		println( " " + gray("Downloading to file: ") + dest_file );

package/lib/marketplace.js

@@ -235,7 +235,7 @@ module.exports = {
 				]
 			});
 			
-			if (warning) println("\n " + yellow(warning));
+			if (warning) warnln("\n " + yellow(warning));
 			println("\n This is the Plugin definition that will be " + (operation == 'create' ? 'created' : 'used to update the installed Plugin') + " when you confirm:");
 			this.jsonOutput(display.plugin);
 			if (display.script) this.printPluginScript(plugin);