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

# Compare Files (zeysdk compare)

Compare Files (zeysdk compare)
==============================

The `compare` command compares local files with their server versions to detect content and property differences.

```bash
zeysdk compare [ASSET_PATH...] [options]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `ASSET_PATH` | Specific asset paths to compare | No | `services/backup.ixml weblets/dashboard.ixml` |

**Options**

| Option | Description |
|--------|-------------|
| `--verbose` | Show detailed output |

**Process**

1. **State Loading**
   - Reads local sync configuration
   - Loads local file metadata
   - Fetches matching server metadata

2. **Comparison**
   - Compares local file hashes with stored sync hashes
   - Compares server hashes with stored sync hashes
   - Checks metadata properties for differences

3. **Output**
   - Groups results by asset type
   - Marks local, server, and conflict states
   - Opens a diff tool when comparing selected files with content differences

**Status Indicators**

| Symbol | Meaning |
|--------|---------|
| `+` | Created locally or added on server |
| `-` | Deleted locally or deleted on server |
| `~` | Modified locally or modified on server |
| `!` | Conflict |
| `<>` | Property conflict |
| `->` | Local changes to be pushed |
| `<-` | Server changes to be pulled |

**Comparison Categories**

The output is organized by asset type:
- Settings
- Services
- Assets
- Resources
- Weblets

**Examples**

```bash
zeysdk compare
zeysdk compare services/backup.ixml weblets/dashboard.ixml
zeysdk compare --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 |
| Diff tool error | Tool launch failed | Select alternative tool |
| Server error | Cannot fetch remote | Check connection/auth |
| Parse error | Invalid file content | Check file format |

**Notes**

- `compare` does not change local files or server state
- `compare` reads the active instance and may fetch remote file contents to support a diff
- `compare` does not acquire `.zeysdk/.sync.lock`; avoid running it during a modifying synchronization command if you need a consistent snapshot
- Passing specific asset paths limits comparison and may open a diff workflow
- Metadata differences are reported separately from content changes
- Diff tool behavior depends on the global CLI configuration
- Remote snapshots reuse the content fetched during comparison, including empty files, and are removed after the comparison tool exits
- Beyond Compare uses its waiting launcher (`bcomp` on macOS, `BComp.com` on Windows), so an already-open window can read the remote snapshot before it is removed
- Beyond Compare's normal result codes (`0`, `1`, `2`, `11`–`14`) finish the comparison without prompting for another tool; launch failures and error codes remain failures
- To use [Hunk](https://www.hunk.dev), install its CLI separately, then select **Default Diff Tool → Hunk** in `zeysdk configure`; the viewer runs in the current terminal
- Custom comparison commands must wait until the viewer is finished before exiting

**Best Practices**

- Run `zeysdk compare` before `push`, `pull`, or `sync` when remote state may have changed
- Compare specific files when investigating a focused change
- Configure a diff tool with `zeysdk configure` for easier conflict review
- Resolve unexpected differences before running forced sync commands