---
title: "Watch Files"
description: "Documentation for Watch Files Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/synchronization/zeysdk-watch"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/synchronization/zeysdk-watch.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/Synchronization/zeysdk-watch.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# 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