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

# Unlink Instance

The `unlink` command removes a local connection to a ZeyOS instance.

```bash
zeysdk unlink [INSTANCE_ID] [options]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `INSTANCE_ID` | Instance to unlink | No | `myinstance` |


**Options**

| Option | Description |
|--------|-------------|
| `--break-lock` | Replace the current sync lock after you verify its operation is no longer running |
| `--verbose` | Show detailed output |

**Process**

1. **Validation**
   - Loads linked instances
   - Uses the active instance automatically when `INSTANCE_ID` is omitted
   - Verifies that the selected instance exists

2. **Unlinking**
   - Removes the explicit non-active instance file, or removes `.zeysdk/sync.json` when unlinking the active instance
   - Prompts for a replacement before unlinking the active instance when multiple other links exist
   - Leaves no active instance when no linked instances remain
   - Restores affected sync files if the local unlink operation fails

**Examples**

```bash
zeysdk unlink myinstance
zeysdk unlink
```

**Error Handling**

| Error | Description | Resolution |
|-------|-------------|------------|
| Missing sync.json | No active instance configuration | Run `zeysdk link` |
| Invalid instance | Instance is not linked | Choose a linked instance |
| Delete failed | Sync files could not be removed | Check local permissions |

**Notes**

- `unlink` removes local connection state for the selected instance
- Remote applications and files are not deleted
- Globally saved host credentials are not deleted; use `zeysdk host remove` for that
- If the active instance is unlinked, another linked instance can become active
- When no linked instances remain, no active instance is set

**Best Practices**

- Use `zeysdk whoami` before unlinking the active instance
- Unlink old development instances that are no longer used
- Keep production instance names easy to recognize
- `unlink` refuses to mutate instance state while another synchronization or instance-state operation owns the project lock