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

# Pull Files

The `pull` command downloads server files to your local environment.

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

**Parameters**

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

Instance-specific settings must match the active instance. For example, when linked to `dev`, `pull settings/settings.production.json` is rejected before requesting server data or changing project files. Select `settings/settings.dev.json` or switch the active instance first. The same rule applies to push, sync, and watch.

**Options**

| Option | Description |
|--------|-------------|
| `-f, --force` | Skip the confirmation before applying the pull |
| `--verbose` | Show detailed output |
| `--debug` | Show detailed debug information |
| `--debug-log` | Write debug output to `.zeysdk/debug.log` |
| `--delete-local-only` | Delete files that only exist locally |
| `--break-lock` | Replace the current sync lock after you verify its operation is no longer running |
| `--dry-run` | Read and report planned changes without applying them |
| `--concurrency <number>` | Maximum concurrent file operations (default: `10`) |
| `-q, --quiet` | Suppress progress indicators |

**Process**

1. **State Loading**
   - Reads `.zeysdk/sync.json`
   - Scans local files and metadata
   - Fetches server state for the active instance

2. **Change Detection**
   - Identifies files that differ from server state
   - Computes hashes for local files
   - Detects files that only exist locally when requested

3. **Pull Execution**
   - Downloads selected or detected server changes
   - Writes files to the local project
   - Updates local sync state after successful changes

4. **Safety Controls**
   - Acquires the project sync lock before scanning and releases its owner token on success, failure, or cancellation
   - Creates a rotating `sync.json` backup for a non-dry-run pull
   - Uses `--dry-run` to preview changes and `--force` to skip the apply confirmation

**Locking**

Pull uses `.zeysdk/.sync.lock`, shared with push, sync, rollout, and recover. If another operation owns the lock, pull exits without applying changes. A stale lock is reclaimed automatically. Use `--break-lock` only after confirming that the recorded process is no longer performing synchronization work; breaking a live lock can allow two destructive operations to overlap.

The lock is released from a `finally` path, including when the user declines the confirmation prompt.

**Dry Run**

`--dry-run` still scans local files, reads the active instance, and calculates the pull and deletion plan. It does not patch the server, write or delete project files, update the manifest or `sync.json`, or create a sync-state backup. When `--debug-log` is also supplied, the requested `.zeysdk/debug.log` is still written. Combining it with `--delete-local-only` reports which local-only files would be removed without deleting them.

**Sync-State Backup Scope**

A non-dry-run pull rotates `.zeysdk/sync.json.backup*` before applying its change set. If pull reports an error, it attempts to restore the newest backup. This recovery covers `sync.json` only: it cannot undo local files or manifest data already changed before a later failure. Use `zeysdk recover --list` to inspect retained backups.

**File Hashing and Synchronization**

The pull process determines which files need to be synchronized by comparing stored hashes with the server hashes returned by the API. Local files are hashed when their file objects are built; there is no timestamp or file-size pre-check before hashing.

The `lastmodified` value returned by the server is stored in `sync.json` for the synced item. It is not used to decide whether a file needs to be pulled.

Use `--verbose` to see detailed comparison and processing output.

**Examples**

```bash
zeysdk pull --verbose
zeysdk pull services/backup.ixml weblets/dashboard.ixml
zeysdk pull -f
zeysdk pull --dry-run
```

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| Missing sync.json | No sync configuration | Run `zeysdk link` first |
| Invalid sync.json | Missing id/url | Re-link instance |
| Network error | Server unreachable | Check connection |
| Auth error | Invalid/expired token | Re-link application |
| Lock error | Sync lock already exists | Wait for current sync or use `--break-lock` |
| Write error | Cannot write local file | Check permissions |

**Warning**

Pull operations can overwrite local changes. Use `zeysdk compare` first to check for local modifications.

**Notes**

- Pull uses the currently active instance
- `--delete-local-only` removes files that exist locally but not on the server
- Local-only files are preserved unless `--delete-local-only` is present
- `--dry-run` reports planned changes without writing files, sync state, or manifest metadata
- Automatic recovery restores only `sync.json`, not project files already written or deleted
- Debug output is useful when investigating sync state or server responses

**Best Practices**

- Run `zeysdk compare` before pulling over local work
- Commit or snapshot important local changes before a broad pull
- Pull specific files when you only need selected server updates
- Use `--break-lock` only after confirming no other sync operation is still running