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