---
title: "Rename Asset"
description: "Documentation for Rename Asset Command in ZeyOS SDK CLI"
canonical_url: "https://www.zeyos.com/sdk/asset-management/zeysdk-rename"
markdown_url: "https://www.zeyos.com/ai/guide/sdk/asset-management/zeysdk-rename.md"
section: "sdk"
authority: "guide"
language: "en"
source_repository: "zeyos/sdk-v2"
source_path: "docs/asset-management/zeysdk-rename.md"
source_revision: "a99897af74253b4dc5af6fecb9301cea0ae18e27"
---

# 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
```