Watch Files

The watch command monitors local files and automatically pushes updates to the ZeyOS server.

Bash

zeysdk watch [options]

Options

Option	Description
--verbose	Show detailed output

Watched Directories

The following directories and files are monitored for changes:

• settings - Configuration files
• services - Service scripts
• weblets - Web components
• resources - Static resources
• assets - Application assets
• zeyos.app.json - Application manifest
• README.md - Application readme

Process

1. Validation

   • Validates active sync configuration
   • Checks each configured watch target before creating its watcher

2. Watching

   • Sets the interactive terminal title to Watch: <app_identifier> using the identifier from zeyos.app.json
   • Watches configured directories recursively
   • Skips missing targets at startup while a root watcher discovers recognized content directories created later
   • Ignores .git, .zeysdk, node_modules, editor temporary files, and unrelated project paths
   • Expands directory events to their relevant files and deduplicates changed paths during a 200 ms debounce window

3. Auto Push

   • Pushes one queued batch at a time
   • Queues changes received during an active push for a following batch
   • Uses force mode for automatic pushes and logs errors without stopping the watchers
   • Retains failed batches and retries them with bounded exponential backoff from 500 ms up to 30 seconds

Locking and Concurrency

Watch does not hold .zeysdk/.sync.lock continuously. Each automatic push acquires the same project lock used by pull, push, sync, rollout, and recover, then releases it when that batch finishes. This serializes batches within one watch process and prevents a batch from overlapping another lock-owning operation.

Watch has no --break-lock option. If a batch cannot acquire the lock or its push fails, the error is logged, the batch remains queued, and watching retries it with backoff. New changes join the retained batch. Run zeysdk push manually if you need to resolve the error outside watch mode.

Automatic Push Scope

Every batch is equivalent to a forced push of its changed paths: there is no confirmation and no dry-run mode. The server may be updated immediately. A non-dry-run push also creates a rotating sync.json backup, but that backup cannot undo a server update.

Removed files and directories are resolved against the manifest and sync baseline, and only those tracked paths are sent for deletion. Untracked removals are ignored; watch never escalates a removal into a whole-project push. Instance-specific settings files for another instance are rejected and excluded from the batch.

Examples

Bash

zeysdk watch
zeysdk watch --verbose

Error Handling

Error	Description	Resolution
Missing sync.json	No sync configuration	Run zeysdk link first
Invalid sync.json	Missing id/url	Re-link instance
Watch error	Cannot monitor directory	Check permissions
Push error	Failed to upload changes	Check connection
Auth error	Invalid/expired token	Re-link application
Lock error	Another synchronization operation owns the lock	Wait for it to finish, then save again or run zeysdk push

Notes

• Changes are pushed automatically
• Pushes run in force mode with a 200 ms debounce and are serialized within the watcher
• Failed batches remain queued and retry with bounded backoff up to 30 seconds
• Watch has no dry-run mode and does not hold the project lock between batches
• Missing targets are skipped at startup; the root watcher can discover recognized content directories created later
• Directory removals send only known descendants; unrelated remote-only files are preserved
• Stop watch with the normal process interrupt (for example, Ctrl+C)

Best Practices

• Use watch only when you intend local changes to reach the active instance immediately
• Confirm the active instance with zeysdk whoami before starting watch
• Avoid watch mode for production instances unless the workflow is intentional
• Stop and restart watch after changing linked instances or credentials