Rename Asset

The rename command renames an existing asset in your ZeyOS application.

Bash

zeysdk rename <OLD_ASSET_PATH> <NEW_ASSET_PATH> [options]

Parameters

Parameter	Description	Required	Example
OLD_ASSET_PATH	Old asset path including class directory and filename	Yes	services/old-service.ixml
NEW_ASSET_PATH	New asset path including class directory and filename	Yes	services/new-service.ixml

Options

Option	Description
--verbose	Show detailed output

Validation Rules

1. Source Validation

   • Asset class must be valid (services, resources, weblets, assets)
   • Source key must exist in zeyos.app.json
   • Source extension must match the MIME type registered in the manifest
   • Source path must remain inside its asset directory and contain no symbolic-link component

2. Destination Validation

   • Asset classes must match between source and destination
   • A different destination key must not exist in the manifest
   • A different destination path must not exist in the filesystem, including as an untracked file or dangling symbolic link
   • New filename must be valid

3. Configuration

   • zeyos.app.json must exist
   • Asset must be properly configured

Process

1. Renames the local file, creating a missing destination parent directory for nested generic assets.
2. Updates the manifest key and MIME type based on the new extension.
3. Records a key-changing rename in .zeysdk/sync.json for compare and sync when that file is available.
4. Restores the original file, manifest, and sync metadata if a later step fails.

Generic assets may move between nested paths, but both paths must remain under assets/. Other asset classes use a single filename. Rename does not update references in source code or other applications.

Error Handling

Error	Description	Resolution	Example Message
Invalid arguments	Missing parameters	Provide both paths	expects at least 2 arguments
Asset class mismatch	Different classes	Use same class	expects the asset class directory to be the same
Invalid asset class	Wrong type	Use valid class	should be a valid asset class: services, resources, weblets, assets
Missing config	No app.json	Initialize app	requires the zeyos.app.json file to exist
Source missing	Source not found	Check source path	requires the asset to exist
Source extension mismatch	Source extension differs from registered MIME type	Use the registered filename	requires the source extension to match
Unsafe path	Path escapes its class directory or contains a symbolic link	Use an in-app path	requires asset file paths to stay inside
Destination exists	Tracked or untracked target exists	Choose a different name	requires the destination file to not exist
Rename failed	File system error	Check permissions	There was a problem renaming the file

Automatic Updates

The following are automatically handled:

1. MIME type updates based on the new extension
2. Manifest key and file-path updates
3. In-process rollback on failure
4. Rename tracking in .zeysdk/sync.json when the manifest key changes

Notes

• Source and destination paths must use the same asset class
• Rename updates metadata and the local file path
• Existing destinations are never intentionally overwritten
• Remote state is not updated until you push or sync
• Rename tracking helps compare and sync display the change as a rename when possible

Best Practices

• Rename before pushing new references to the asset
• Keep asset keys stable once they are used by other apps or integrations
• Use zeysdk compare after renaming to verify the pending operation
• Prefer one rename per asset over rename-plus-content edits in the same change

Examples

Bash

# Rename a service
zeysdk rename services/old-backup.ixml services/new-backup.ixml --verbose
# Output:
# Loading assets info.
# Renaming file.
# Updating assets info.
# Rename was completed successfully.

# Rename a weblet (changing extension)
zeysdk rename weblets/dashboard.ixml weblets/dashboard-test.ixml
# Updates mimetype automatically

# Rename a resource
zeysdk rename resources/old-logo.png resources/new-logo.png

# Move a nested generic asset within assets/
zeysdk rename assets/drafts/logo.svg assets/images/logo.svg