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

# Use Instance

The `use` command switches the active ZeyOS instance for the current application.

```bash
zeysdk use [INSTANCE_ID] [options]
```

**Parameters**

| Parameter | Description | Required | Example |
|-----------|-------------|----------|---------|
| `INSTANCE_ID` | Instance to switch to | 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
   - Prompts for an instance when none is provided
   - Verifies that the selected instance exists

2. **Activation**
   - Renames the current active sync file to its instance-specific filename
   - Makes the selected instance-specific sync file active as `.zeysdk/sync.json`
   - Restores the affected sync files if switching fails
   - Clears cached views for the new instance

**Examples**

```bash
zeysdk use myinstance
zeysdk use
```

**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 |
| Switch failed | Sync files could not be updated | Check local permissions |

**Notes**

- `use` changes the active local instance for the current application
- `use` refuses to switch while another synchronization or instance-state operation owns the project lock
- The command does not modify remote application data
- Cached views are cleared after switching instances
- Commands such as `push`, `pull`, `sync`, and activity changes use the active instance

**Best Practices**

- Run `zeysdk whoami` after switching to confirm the target instance
- Keep instance IDs descriptive enough to avoid confusing environments
- Compare before pushing after switching to a different instance
- Avoid switching instances while another CLI operation is running