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