Clone Application

The clone command copies an existing ZeyOS application from a remote instance.

Bash

zeysdk clone <INSTANCE_ID> <APP_ID> [TARGET_DIRECTORY] [options]

Parameters

Parameter	Description	Required	Default	Example
INSTANCE_ID	Source instance ID	Yes	-	dev-instance
APP_ID	Application ID	Yes	-	my-app
TARGET_DIRECTORY	Destination path	No	Same as APP_ID	apps/my-app

Options

Option	Description
--verbose	Show detailed output
--token <token>	SDK token for non-interactive linking
--url <url>	Instance URL for non-interactive linking

Process

1. Directory Setup

   • If TARGET_DIRECTORY not provided, uses APP_ID as directory name
   • Requires the target's parent directory to exist
   • Refuses to overwrite any existing target path
   • Creates a uniquely named staging directory beside the final target

2. App Creation

   • Creates the local scaffold in the staging directory
   • Sets up initial scaffolding

3. Instance Linking

   • Links to specified instance
   • Validates credentials and connection
   • Requires APP_ID to already exist remotely; clone will not create it

4. Data Sync

   • Performs force pull to sync all app data
   • Retrieves complete application state
   • Renames the completed staging directory to TARGET_DIRECTORY
   • Removes staging data on any create, link, pull, or finalization failure

Error Handling

Error	Description	Resolution
Directory exists	Target directory already exists	Choose different target directory
Parent missing	Parent of the target path does not exist	Create the parent directory first
Creation failed	App creation error	Check app identifier and permissions
Link failed	Instance linking error	Verify instance ID and connectivity
Remote app missing	APP_ID does not exist on the source instance	Verify the app ID and source instance
Pull failed	Data sync error	Check network and try again

Notes

• TARGET_DIRECTORY defaults to APP_ID
• The target directory must not already exist
• The target appears only after create, link, and pull have all succeeded
• For a fully non-interactive clone, pass both --token and --url unless a matching stored host supplies the missing value
• A failure after authentication removes the local staging directory, but a credential saved by the successful link step can remain in the global host store
• The resulting project is linked to the source instance

Best Practices

• Clone into a clean workspace
• Use a descriptive target directory when cloning multiple environments
• Run zeysdk compare after cloning if you need to verify local and remote state
• Avoid editing files during the initial clone and pull sequence